@autional-cn/shared 0.1.0-rc

package/src/hooks/__tests__/useBootstrap.test.tsx

@@ -0,0 +1,91 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+// ============================================================
+// F-W5b 回归锁：useBootstrap 无会话时必须 'idle'，不得 'loading'
+//  —— platform-console LayoutWrapper 以 bootstrap==='loading' 挡 Outlet，
+//     而 RequireAuth（唯一登录交棒点）在 Outlet 内 ⇒ 无会话冷启动永停 Spin。
+// ============================================================
+
+const { mockQueries } = vi.hoisted(() => ({
+	mockQueries: {
+		perms: { data: undefined as unknown, isError: false },
+		tenants: { data: undefined as unknown, isError: false },
+	},
+}));
+
+vi.mock('../../auth/auth-queries', () => ({
+	usePermissionsQuery: () => mockQueries.perms,
+	useTenantsQuery: () => mockQueries.tenants,
+}));
+
+import { useBootstrap } from '../useBootstrap';
+import { useAuthStore } from '../../auth/store';
+
+const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+
+function wrapper({ children }: { children: React.ReactNode }) {
+	return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}
+
+function resetAuthStore(): void {
+	useAuthStore.setState({
+		user: null,
+		accessToken: null,
+		refreshToken: null,
+		tenants: [],
+		currentTenantId: null,
+		permissions: [],
+		isAuthenticated: false,
+	});
+	window.localStorage.clear();
+}
+
+describe('useBootstrap（F-W5b 无会话语义）', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		resetAuthStore();
+		mockQueries.perms = { data: undefined, isError: false };
+		mockQueries.tenants = { data: undefined, isError: false };
+	});
+
+	afterEach(() => {
+		cleanup();
+		resetAuthStore();
+	});
+
+	it('无 token → idle（回归锁：返回 loading 会让 Layout 消费者永停 Spin）', () => {
+		const { result } = renderHook(() => useBootstrap(), { wrapper });
+		expect(result.current).toBe('idle');
+		expect(result.current).not.toBe('loading');
+	});
+
+	it('无 token 且 store 残留数据 → 仍 idle（登出/切换租户后的残态不得冒充 ready）', () => {
+		useAuthStore.setState({
+			accessToken: null,
+			permissions: ['user.read'],
+			tenants: [{ id: 't1', name: 'demo', role: 'member' }],
+		});
+		const { result } = renderHook(() => useBootstrap(), { wrapper });
+		expect(result.current).toBe('idle');
+	});
+
+	it('有 token + store 已缓存权限与租户 → ready', () => {
+		useAuthStore.setState({
+			accessToken: 'token-xyz',
+			permissions: ['user.read'],
+			tenants: [{ id: 't1', name: 'demo', role: 'member' }],
+		});
+		const { result } = renderHook(() => useBootstrap(), { wrapper });
+		expect(result.current).toBe('ready');
+	});
+
+	it('有 token 但查询尚未到达 → loading（保持既有等待语义）', () => {
+		useAuthStore.setState({ accessToken: 'token-xyz' });
+		const { result } = renderHook(() => useBootstrap(), { wrapper });
+		expect(result.current).toBe('loading');
+	});
+});

package/src/hooks/__tests__/useCurrentRole.test.tsx

@@ -0,0 +1,122 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { renderHook, act, cleanup } from '@testing-library/react';
+import { useAuthStore } from '../../auth/store';
+import { useCurrentRole } from '../useCurrentRole';
+
+const TENANTS = [
+	{ id: 'tenant-a', name: 'Tenant A', role: 'admin' },
+	{ id: 'tenant-b', name: 'Tenant B', role: 'member' },
+];
+
+/** 重置 store + localStorage，避免跨用例污染（AC-002 约定） */
+function resetAuthStore(): void {
+	useAuthStore.setState({
+		user: null,
+		accessToken: null,
+		refreshToken: null,
+		tenants: [],
+		currentTenantId: null,
+		permissions: [],
+		isAuthenticated: false,
+	});
+	window.localStorage.clear();
+}
+
+describe('useCurrentRole (AC-002 响应式，zustand selector 订阅 store 本身)', () => {
+	beforeEach(() => {
+		resetAuthStore();
+	});
+
+	afterEach(() => {
+		cleanup();
+		resetAuthStore();
+	});
+
+	it('初始空 store → null', () => {
+		const { result } = renderHook(() => useCurrentRole());
+		expect(result.current).toBeNull();
+	});
+
+	it('渲染后直写 store（setState）→ re-render + 新值', () => {
+		const { result } = renderHook(() => useCurrentRole());
+		expect(result.current).toBeNull();
+
+		act(() => {
+			useAuthStore.setState({ tenants: TENANTS, currentTenantId: 'tenant-a' });
+		});
+		expect(result.current).toBe('admin');
+
+		act(() => {
+			useAuthStore.setState({ currentTenantId: 'tenant-b' });
+		});
+		expect(result.current).toBe('member');
+	});
+
+	it('updateTenants / updateCurrentTenant action 后重渲染新值', () => {
+		const { result } = renderHook(() => useCurrentRole());
+		expect(result.current).toBeNull();
+
+		act(() => {
+			useAuthStore.getState().setTenants(TENANTS);
+		});
+		expect(result.current).toBeNull(); // 有租户但未选 → 不猜测
+
+		act(() => {
+			useAuthStore.getState().setCurrentTenant('tenant-b');
+		});
+		expect(result.current).toBe('member');
+
+		act(() => {
+			useAuthStore.getState().switchTenant('tenant-a');
+		});
+		expect(result.current).toBe('admin');
+	});
+
+	it('logout 清空（tenants [] / currentTenantId null）→ null', () => {
+		const { result } = renderHook(() => useCurrentRole());
+
+		act(() => {
+			useAuthStore.setState({ tenants: TENANTS, currentTenantId: 'tenant-a' });
+		});
+		expect(result.current).toBe('admin');
+
+		act(() => {
+			useAuthStore.getState().clearAuth();
+		});
+		expect(result.current).toBeNull();
+	});
+
+	it('selector 原语稳定：无关字段变更不触发 re-render（Object.is 比较）', () => {
+		let renderCount = 0;
+		const { result } = renderHook(() => {
+			renderCount++;
+			return useCurrentRole();
+		});
+
+		act(() => {
+			useAuthStore.setState({ tenants: TENANTS, currentTenantId: 'tenant-a' });
+		});
+		expect(result.current).toBe('admin');
+		const afterRoleSet = renderCount;
+
+		// 无关字段变更（permissions）→ selector 结果相同 → 不 re-render
+		act(() => {
+			useAuthStore.setState({ permissions: ['tenant:user:read'] });
+		});
+		expect(result.current).toBe('admin');
+		expect(renderCount).toBe(afterRoleSet);
+
+		// 相同 role、不同数组引用 → 返回值仍是 string 原语 → 不 re-render
+		act(() => {
+			useAuthStore.setState({
+				tenants: [
+					{ id: 'tenant-a', name: 'Tenant A', role: 'admin' },
+					{ id: 'tenant-b', name: 'Tenant B', role: 'member' },
+				],
+			});
+		});
+		expect(result.current).toBe('admin');
+		expect(renderCount).toBe(afterRoleSet);
+	});
+});

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/useLogout.ts

@@ -0,0 +1,33 @@
+/**
+ * 统一的登出 Hook
+ * 所有 portal 必须使用此 hook 处理登出，确保清理逻辑一致
+ * 委托给 AuthService.logout() 统一实现
+ */
+
+import { useCallback } from 'react';
+import { buildLogoutUrl } from '../auth/roles';
+
+/**
+ * 统一的登出 Hook
+ * 委托 AuthService.logout() 执行清理（清除内存状态、localStorage、cookie、token 吊销），
+ * 然后跳转到登录页。
+ */
+export function useLogout() {
+	return useCallback(() => {
+		const performLogout = async () => {
+			// 在 clearAuth/跳转前捕获当前 URL，避免时序竞争：
+			// AuthService.logout() 的 clearAuth 会触发 store 变化，
+			// 页面可能因此先导航到 '/'，导致后续读到的 window.location.href 丢失租户 slug
+			const currentUrl = 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` 登出意图标记：入口路由据此先
+			// 终结会话再落 brand，而不是把带会话的回程当普通深链直送登录页（会静默重登）。
+			window.location.href = buildLogoutUrl(currentUrl);
+		};
+		performLogout();
+	}, []);
+}

package/src/hooks/usePermission.ts

@@ -0,0 +1,116 @@
+/**
+ * 权限检查 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'],
+	'user:read': ['tenant:user:read', 'tenant:dashboard:read', 'self:profile:read'],
+	'user:update': ['tenant:user:read'],
+	'user:delete': ['tenant:user:read'],
+	'role:create': ['tenant:role:read'],
+	'role:read': ['tenant:role:read'],
+	'role:update': ['tenant:role:read'],
+	'role:delete': ['tenant:role:read'],
+	'audit:read': ['tenant:audit:read', 'tenant:compliance: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 };
+}