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

package/src/hooks/useAuth.ts

@@ -0,0 +1,239 @@
+/**
+ * useAuth — 认证状态 React Hook
+ *
+ * 基于 useSyncExternalStore 订阅 AuthService 事件，
+ * 实现零额外渲染的认证状态响应。
+ *
+ * 替代以下模式的直接 useAuthStore 使用：
+ *   const { isAuthenticated, user, permissions } = useAuthStore();
+ * 改为:
+ *   const { isAuthenticated, user, permissions } = useAuth();
+ *
+ * useAuthActions() 替代直接调用 AuthService 静态方法：
+ *   const { login, logout, setCurrentTenant } = useAuthActions();
+ *   await logout();
+ *
+ * @see docs/architecture/auth-service-migration-plan.md
+ */
+
+'use client';
+
+import { useSyncExternalStore, useCallback } from 'react';
+import { AuthService } from '../auth/service';
+import type { User } from '../types';
+
+// ============ Types ============
+
+export interface AuthSnapshot {
+	isAuthenticated: boolean;
+	user: User | null;
+	userId: string | null;
+	accessToken: string | null;
+	currentTenantId: string | null;
+	permissions: string[];
+	tenants: Array<{ id: string; name: string; role: string }>;
+}
+
+export interface AuthActions {
+	/** 跳转到 OAuth 登录页或 auth-pages */
+	login: (params?: { clientId?: string; redirectUri?: string }) => Promise<void>;
+	/** 统一登出（清除所有状态 + 跳转登录页） */
+	logout: () => Promise<void>;
+	/** 设置当前租户 */
+	setCurrentTenant: (tenantId: string) => void;
+	/** 更新用户信息 */
+	updateUser: (user: Partial<User>) => void;
+	/** 设置权限列表 */
+	updatePermissions: (permissions: string[]) => void;
+	/** 设置租户列表 */
+	updateTenants: (tenants: Array<{ id: string; name: string; role: string }>) => void;
+}
+
+// ============ Snapshot with Change Detection ============
+
+/** 浅比较两个快照 — 只有实际变化时才返回新引用，避免不必要 re-render */
+function shallowEqual(a: AuthSnapshot, b: AuthSnapshot): boolean {
+	if (a.isAuthenticated !== b.isAuthenticated) return false;
+	if (a.userId !== b.userId) return false;
+	if (a.accessToken !== b.accessToken) return false;
+	if (a.currentTenantId !== b.currentTenantId) return false;
+	if (a.user?.username !== b.user?.username) return false;
+	if (a.user?.email !== b.user?.email) return false;
+	if (a.permissions.length !== b.permissions.length) return false;
+	if (a.tenants.length !== b.tenants.length) return false;
+	// 简化的数组比较：内容变更时下个事件循环会触发重新计算
+	return true;
+}
+
+let lastSnapshot: AuthSnapshot | null = null;
+
+/** 所有事件触发的回调（统一入口，减少事件注册数量） */
+const AUTH_EVENTS = [
+	'auth:login',
+	'auth:logout',
+	'auth:user-updated',
+	'auth:tokens-refreshed',
+	'auth:tenant-changed',
+	'auth:tenants-updated',
+	'auth:permissions-updated',
+] as const;
+
+function buildSnapshot(): AuthSnapshot {
+	const user = AuthService.getUser();
+	return {
+		isAuthenticated: AuthService.isAuthenticated(),
+		user,
+		userId: user?.id || null,
+		accessToken: AuthService.getAccessToken(),
+		currentTenantId: AuthService.getCurrentTenantId(),
+		permissions: AuthService.getPermissions(),
+		tenants: AuthService.getTenants(),
+	};
+}
+
+function getSnapshot(): AuthSnapshot {
+	const now = buildSnapshot();
+	if (lastSnapshot && shallowEqual(lastSnapshot, now)) {
+		return lastSnapshot;
+	}
+	lastSnapshot = now;
+	return now;
+}
+
+function subscribeToAuth(callback: () => void): () => void {
+	const unsubs = AUTH_EVENTS.map((event) => AuthService.subscribe(event, callback));
+	return () => unsubs.forEach((u) => u());
+}
+
+// ============ useAuth ============
+
+/**
+ * 响应式认证状态 Hook。
+ * 返回完整认证快照，含用户、token、权限、租户信息。
+ * 内部使用 shallowEqual 缓存，只有实际变化时才触发 re-render。
+ *
+ * 用法:
+ * ```tsx
+ * const { isAuthenticated, user, permissions, currentTenantId } = useAuth();
+ * ```
+ */
+export function useAuth(): AuthSnapshot {
+	const snapshot = useSyncExternalStore(subscribeToAuth, getSnapshot);
+	return snapshot;
+}
+
+// ============ Selector Hooks ============
+
+/**
+ * 是否已认证（只读，仅当此值变化时 re-render）
+ */
+export function useIsAuthenticated(): boolean {
+	const { isAuthenticated } = useAuth();
+	return isAuthenticated;
+}
+
+/**
+ * 当前用户（只读，仅当此值变化时 re-render）
+ */
+export function useUser(): User | null {
+	const { user } = useAuth();
+	return user;
+}
+
+/**
+ * 当前用户 ID（只读，仅当此值变化时 re-render）
+ */
+export function useUserId(): string | null {
+	const { userId } = useAuth();
+	return userId;
+}
+
+/**
+ * 当前 access token（只读，仅当此值变化时 re-render）
+ */
+export function useAccessToken(): string | null {
+	const { accessToken } = useAuth();
+	return accessToken;
+}
+
+/**
+ * 当前权限列表（只读，仅当此值变化时 re-render）
+ */
+export function useAuthPermissions(): string[] {
+	const { permissions } = useAuth();
+	return permissions;
+}
+
+/**
+ * 当前租户 ID（只读，仅当此值变化时 re-render）
+ */
+export function useCurrentTenantId(): string | null {
+	const { currentTenantId } = useAuth();
+	return currentTenantId;
+}
+
+/**
+ * 租户列表（只读，仅当此值变化时 re-render）
+ */
+export function useTenants(): Array<{ id: string; name: string; role: string }> {
+	const { tenants } = useAuth();
+	return tenants;
+}
+
+// ============ useAuthActions ============
+
+/**
+ * 认证操作 Hook。
+ * 提供 login/logout/setCurrentTenant/update* 等操作，
+ * 替代组件中直接调用 AuthService 静态方法。
+ *
+ * 用法:
+ * ```tsx
+ * const { logout, setCurrentTenant } = useAuthActions();
+ * await logout();
+ * setCurrentTenant('new-tenant-id');
+ * ```
+ */
+export function useAuthActions(): AuthActions {
+	const login = useCallback(
+		async (params?: { clientId?: string; redirectUri?: string }): Promise<void> => {
+			if (params?.clientId) {
+				const { initiateOAuthLogin } = await import('../auth/oauth-login');
+				return initiateOAuthLogin(params.clientId, params.redirectUri);
+			}
+			const { buildLoginUrl } = await import('../auth/roles');
+			window.location.href = buildLoginUrl(window.location.href);
+		},
+		[],
+	);
+
+	const logout = useCallback(async (): Promise<void> => {
+		// 在 clearAuth 前捕获 URL，避免时序竞争（与 useLogout 一致）
+		const currentUrl = typeof window !== 'undefined' ? window.location.href : '';
+		await AuthService.logout();
+		const { buildLogoutUrl } = await import('../auth/roles');
+		// 传当前 URL 作为 returnUrl，保留租户 slug + 登出意图标记（与 useLogout 一致）
+		window.location.href = buildLogoutUrl(currentUrl);
+	}, []);
+
+	const setCurrentTenant = useCallback((tenantId: string): void => {
+		AuthService.updateCurrentTenant(tenantId);
+	}, []);
+
+	const updateUser = useCallback((user: Partial<User>): void => {
+		AuthService.updateUser(user);
+	}, []);
+
+	const updatePermissions = useCallback((permissions: string[]): void => {
+		AuthService.updatePermissions(permissions);
+	}, []);
+
+	const updateTenants = useCallback(
+		(tenants: Array<{ id: string; name: string; role: string }>): void => {
+			AuthService.updateTenants(tenants);
+		},
+		[],
+	);
+
+	return { login, logout, setCurrentTenant, updateUser, updatePermissions, updateTenants };
+}

package/src/hooks/useBootstrap.ts

@@ -0,0 +1,74 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useAuthStore } from '../auth/store';
+import { AuthService } from '../auth/service';
+import { usePermissionsQuery, useTenantsQuery } from '../auth/auth-queries';
+
+export type BootstrapState = 'idle' | 'loading' | 'ready' | 'error';
+
+/**
+ * 应用启动数据加载 Hook。
+ *
+ * 使用 React Query 缓存权限和租户数据（5 分钟 staleTime），
+ * 避免重复请求。首次加载时自动写入 AuthService。
+ *
+ * 返回 BootstrapState 用于 Portal Layout 展示加载状态。
+ */
+export function useBootstrap(): BootstrapState {
+	const currentTenantId = useAuthStore((s) => s.currentTenantId);
+	const permissionsStore = useAuthStore((s) => s.permissions);
+	const tenantsStore = useAuthStore((s) => s.tenants);
+
+	// 无有效 token 时不发起权限/租户查询。
+	// 未登录时这些查询必然 401 → apiClient 401 拦截 → refreshToken() 无 refresh token
+	// → onUnauthorized() 立即 buildLoginUrl 302，抢跑 RequireAuth 的 OAuth PKCE 决策
+	// （跨域 admin 场景偶发：本应跳 authorize，实际却 302 回 auth 登录页）。
+	// 未登录的跳转决策统一交给 RequireAuth（OAuth PKCE 或 buildLoginUrl）。
+	const rawToken = AuthService.getAccessToken();
+	const hasToken = !!rawToken && rawToken !== 'undefined' && rawToken !== 'null';
+
+	// React Query: 5 分钟缓存，自动管理 loading/error
+	// key 中包含 currentTenantId，切换租户时自动重新请求
+	const permsQuery = usePermissionsQuery(currentTenantId, hasToken);
+	const tentsQuery = useTenantsQuery(currentTenantId, hasToken);
+
+	// 同步 React Query 结果到 AuthService（写入 store 触发 persist）
+	useEffect(() => {
+		if (permsQuery.data && permsQuery.data.length > 0) {
+			AuthService.updatePermissions(permsQuery.data);
+		}
+	}, [permsQuery.data]);
+
+	useEffect(() => {
+		if (tentsQuery.data && tentsQuery.data.length > 0) {
+			AuthService.updateTenants(tentsQuery.data);
+		}
+	}, [tentsQuery.data]);
+
+	// 无会话 = 无数据可引导：返回 'idle'，登录交棒由 RequireAuth/守卫决策（见上）。
+	// 不得返回 'loading'：Layout 消费者（platform-console）以 bootstrap==='loading'
+	// 挡 Outlet，而 RequireAuth 在 Outlet 里 ⇒ 无会话冷启动永停 Spin、守卫永不挂载（F-W5b）。
+	if (!hasToken) {
+		return 'idle';
+	}
+
+	// 已缓存数据 → 立即 ready
+	if (permissionsStore.length > 0 && tenantsStore.length > 0) {
+		return 'ready';
+	}
+
+	// React Query 数据到达（即使是 stale）
+	if (permsQuery.data || tentsQuery.data) {
+		return 'ready';
+	}
+
+	// 两个请求都失败 — keep reporting loading to prevent re-render loops
+	// (OAuth PKCE or BFF redirect will resolve the page before error matters)
+	if (permsQuery.isError && tentsQuery.isError) {
+		return 'loading';
+	}
+
+	// 等待中
+	return 'loading';
+}

package/src/hooks/useCurrentRole.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import { useAuthStore } from '../auth/store';
+
+/**
+ * 响应式当前角色 hook。
+ * 用 zustand selector 订阅 store 本身 —— loadAuthExtras 直写 store action
+ * 不发 AuthService 事件，仅订阅事件会在密码登录路径漏刷新（ADR-002）。
+ * selector 返回 string 原语 → Object.is 比较引用稳定，不会无限重渲染。
+ * 前端角色仅用于 UX 呈现；安全判断由后端 rbac-backed 授权强制（AC-008）。
+ */
+export function useCurrentRole(): string | null {
+	return useAuthStore((s) => {
+		if (!s.tenants || s.tenants.length === 0) return null;
+		if (!s.currentTenantId) return null;
+		return s.tenants.find((t) => t.id === s.currentTenantId)?.role ?? null;
+	});
+}

package/src/hooks/useCurrentTenantIdOr.ts

@@ -0,0 +1,29 @@
+'use client';
+
+// 当前租户 ID 的**带显式回落**版本。
+//
+// 为什么需要它（而不是让各门户各写一份）：admin 与 platform 各有一份 hooks/use-tenant.ts，
+// 同名同签名、语义却不同 —— admin 的 useTenantIdOr 会回落 tenants[0]，platform 的直接返回入参。
+// 那个差别不是风格：admin 的注释记着 BUG-013（硬编码 'default-tenant' 导致 data-classification 等页 404），
+// 而 tenants[0] 是「已登录但没选租户」时唯一正确的答案。同一个函数名两种语义，迟早会有人在错误的那份上写新功能。
+//
+// 与 useCurrentTenantId() 的分工：那个是**只读、可空、诚实**的窄 hook（无租户就是 null）；
+// 这个在调用方确实需要一个字符串时用，并且**把回落值写在调用点上** —— 让「没有租户时会发生什么」看得见。
+
+import { useCurrentTenantId } from './useAuth';
+import { useTenants } from './useAuth';
+
+/**
+ * 当前租户 ID，缺失时回落：已登录但未选租户 → 取 tenants[0].id；连租户列表都空 → 用调用方给的 fallback。
+ *
+ * 用法：
+ *   const tenantId = useCurrentTenantIdOr('');          // 明确接受「空字符串」这一种无租户表示
+ *   const tenantId = useCurrentTenantIdOr('default');   // 或给一个明确的兜底
+ */
+export function useCurrentTenantIdOr(fallback: string): string {
+	const currentTenantId = useCurrentTenantId();
+	const tenants = useTenants();
+	if (currentTenantId) return currentTenantId;
+	if (tenants && tenants.length > 0 && tenants[0].id) return tenants[0].id;
+	return fallback;
+}

package/src/hooks/useLogout.ts

@@ -0,0 +1,42 @@
+/**
+ * 统一的登出 Hook
+ * 所有 portal 必须使用此 hook 处理登出，确保清理逻辑一致
+ * 委托给 AuthService.logout() 统一实现
+ */
+
+import { useCallback } from 'react';
+import { buildLogoutUrl } from '../auth/roles';
+import { traceRedirect } from '../auth/auth-trace';
+
+/**
+ * 统一的登出 Hook
+ * 委托 AuthService.logout() 执行清理（清除内存状态、localStorage、cookie、token 吊销），
+ * 然后跳转到登录页。
+ *
+ * 落点口径（AUTH-40）：回程可用 `returnUrl` 显式覆盖——供当前 URL 无租户段、
+ * 调用方另持租户上下文的场景（auth 域裸 `/logout` 用登录期锚定标记补回）；
+ * 缺省用捕获的当前 URL。EntryRouter 据回程解析租户 → `/<slug>/login`，否则 brand。
+ */
+export function useLogout(opts?: { returnUrl?: string }) {
+	const returnUrl = opts?.returnUrl;
+	return useCallback(() => {
+		const performLogout = async () => {
+			// 在 clearAuth/跳转前捕获当前 URL，避免时序竞争：
+			// AuthService.logout() 的 clearAuth 会触发 store 变化，
+			// 页面可能因此先导航到 '/'，导致后续读到的 window.location.href 丢失租户 slug
+			const currentUrl =
+				returnUrl || (typeof window !== 'undefined' ? window.location.href : '');
+
+			// AuthService.logout() 统一处理：clearAuth + LS 清理 + cookie 清理 + token 吊销
+			const { AuthService } = await import('../auth/service');
+			await AuthService.logout();
+
+			// buildLogoutUrl = auth 域裸根 + `logout=1` 登出意图标记：入口路由据此先
+			// 终结会话再定落点（能解析出租户 → 裸 /<slug>/login；否则 brand 裸根），
+			// 而不是把带会话的回程当普通深链直送登录页（会静默重登）。
+			// funnel：用户主动行为，静默直跳（assign 保持原 href 历史语义）；仅记 trace。
+			traceRedirect(buildLogoutUrl(currentUrl), { reason: 'logout', assign: true });
+		};
+		performLogout();
+	}, [returnUrl]);
+}

package/src/hooks/usePermission.ts

@@ -0,0 +1,128 @@
+/**
+ * 权限检查 Hook
+ * 基于 effective_permissions 数组进行前端权限控制
+ * 通过 zustand selector 订阅 store 本身实现响应式更新（ADR-002）——
+ * loadAuthExtras 直写 store action 不发 AuthService 事件，仅订阅事件会漏刷新。
+ */
+
+import { useAuthStore } from '../auth/store';
+import { useCurrentRole } from './useCurrentRole';
+
+export interface PermissionResult {
+	can: (permission: string) => boolean;
+	canAny: (...permissions: string[]) => boolean;
+	canAll: (...permissions: string[]) => boolean;
+	isSuperAdmin: boolean;
+	isTenantAdmin: boolean;
+	isAuditor: boolean;
+	isDeveloper: boolean;
+	isEndUser: boolean;
+}
+
+const PERMISSION_MAP: Record<string, string[]> = {
+	'user:create': ['tenant:user:read'],
+	// B1 裁撤（TASK-AB1-12）：去掉 'tenant:user:read' —— member/guest 仅持 user:read 不再见 /users；
+	// user_manager 经 'user:create' 仍映射到 'tenant:user:read'（不回归）。
+	'user:read': ['tenant:dashboard:read', 'self:profile:read'],
+	'user:update': ['tenant:user:read'],
+	'user:delete': ['tenant:user:read'],
+	'role:create': ['tenant:role:read'],
+	// B2 裁撤（TASK-AB1-12）：role:read 不再映射 'tenant:role:read' —— security_admin
+	// （11 码集仅 role:read）不再见 /roles 与 /role-activations；无其他映射源可授予导航键。
+	'role:read': [],
+	'role:update': ['tenant:role:read'],
+	'role:delete': ['tenant:role:read'],
+	'audit:read': ['tenant:audit:read', 'tenant:compliance:read'],
+	// D4 补源（TASK-AB1-12）：NHI 父键 + 叶（/agents、/robots、/devices、/policies/nhi）可见性
+	'agent:read': ['tenant:nhi:read'],
+	'robot:read': ['tenant:nhi:read'],
+	'device:read': ['tenant:nhi:read'],
+	// D4 补源（TASK-AB1-12）：/status 监控面（status:read）
+	'status:read': ['tenant:monitor:read'],
+	// D4 补源（TASK-AB1-12）：/oauth-clients 开发者面（oauth:read）
+	'oauth:read': ['tenant:oauth:read'],
+	'profile:read': ['tenant:profile:read'],
+	'profile:write': ['tenant:profile:read'],
+	'profile:archive': ['tenant:profile:read'],
+	'profile:export': ['tenant:profile:read', 'tenant:compliance:read'],
+	'profile:delete': ['tenant:profile:read'],
+	'profile:manage': ['tenant:profile:read'],
+	'system:config': [
+		'tenant:permission:read',
+		'tenant:session:read',
+		'tenant:secret:manage',
+		'tenant:department:read',
+		'tenant:member:read',
+		'tenant:app:read',
+		'tenant:idp:read',
+		'tenant:webhook:read',
+		'tenant:mfa:read',
+		'tenant:security:read',
+		'tenant:branding:read',
+		'tenant:notification:read',
+		'tenant:communication:read',
+		'tenant:storage:read',
+		'tenant:wallet:read',
+		'tenant:point:read',
+	],
+};
+
+const EMPTY_PERMS: string[] = [];
+
+export function usePermission(): PermissionResult {
+	// zustand selector 订阅 store：permissions 数组取 store 原引用（或模块级常量
+	// EMPTY_PERMS），role 为 string 原语 —— 两者均天然引用稳定，值相等即不触发
+	// 重渲染（Object.is 比较），根治 React #185 (Maximum update depth exceeded)。
+	const permissions = useAuthStore((s) => s.permissions || EMPTY_PERMS);
+	const perms = permissions;
+
+	const role = useCurrentRole();
+	const isAdminRole = role === 'super_admin' || role === 'admin';
+
+	// Build effective permission set: backend resource:action → frontend scope:resource:action
+	const effectivePerms = new Set<string>();
+	for (let i = 0; i < perms.length; i++) {
+		const p = perms[i];
+		if (p) {
+			effectivePerms.add(p);
+			const mapped = PERMISSION_MAP[p];
+			if (mapped) {
+				for (let j = 0; j < mapped.length; j++) {
+					effectivePerms.add(mapped[j]);
+				}
+			}
+		}
+	}
+	const allPerms = Array.from(effectivePerms);
+
+	const can = (permission: string): boolean => {
+		if (effectivePerms.has(permission)) return true;
+		if (isAdminRole && permission.startsWith('tenant:')) return true;
+		if (isAdminRole && permission.startsWith('platform:')) return true;
+		return false;
+	};
+
+	const canAny = (...permissionList: string[]): boolean =>
+		permissionList.some((p) => effectivePerms.has(p));
+
+	const canAll = (...permissionList: string[]): boolean =>
+		permissionList.every((p) => effectivePerms.has(p));
+
+	const isSuperAdmin = allPerms.some((p) => p.startsWith('platform:'));
+
+	const isTenantAdmin = allPerms.some(
+		(p) => p.startsWith('tenant:') && (p.endsWith(':manage') || p.endsWith(':write')),
+	);
+
+	const isAuditor =
+		allPerms.some((p) => p.startsWith('tenant:audit:')) &&
+		!allPerms.some((p) => p.includes(':write') || p.includes(':delete'));
+
+	const isDeveloper =
+		allPerms.some((p) => p.startsWith('tenant:app:')) &&
+		!allPerms.some((p) => p.startsWith('tenant:user:'));
+
+	const isEndUser = allPerms.every((p) => p.startsWith('self:'));
+
+	return { can, canAny, canAll, isSuperAdmin, isTenantAdmin, isAuditor, isDeveloper, isEndUser };
+}