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

package/src/auth/store.ts

@@ -0,0 +1,227 @@
+/**
+ * Autional 全局认证状态管理 (Zustand)
+ * 所有前端应用共用同一个 auth store
+ *
+ * 职责划分（AC-008）：前端角色（tenants[].role 派生）仅用于 UX 呈现；
+ * 安全判断由后端 rbac-backed 授权强制，前端不做凭角色放行的敏感操作。
+ */
+
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+import type { User } from '../types';
+import { traceRedirect } from './auth-trace';
+import { decodeJwtPayload } from './jwt-payload';
+
+interface AuthState {
+	// State
+	user: User | null;
+	accessToken: string | null;
+	refreshToken: string | null;
+	tenants: Array<{ id: string; name: string; role: string }>;
+	currentTenantId: string | null;
+	permissions: string[];
+	isAuthenticated: boolean;
+
+	// Actions
+	setAuth: (accessToken: string, refreshToken: string, user: User) => void;
+	setTokens: (accessToken: string, refreshToken: string) => void;
+	setUser: (user: User) => void;
+	setTenants: (tenants: Array<{ id: string; name: string; role: string }>) => void;
+	setCurrentTenant: (tenantId: string) => void;
+	switchTenant: (tenantId: string) => void;
+	setPermissions: (permissions: string[]) => void;
+	clearAuth: () => void;
+}
+
+export const useAuthStore = create<AuthState>()(
+	persist(
+		(set) => ({
+			user: null,
+			accessToken: null,
+			refreshToken: null,
+			tenants: [],
+			currentTenantId: null,
+			permissions: [],
+			isAuthenticated: false,
+
+			setAuth: (accessToken, refreshToken, user) => {
+				if (!user) return;
+				const validToken = accessToken && accessToken !== 'undefined' && accessToken !== 'null';
+				set({
+					accessToken: validToken ? accessToken : null,
+					refreshToken: validToken ? refreshToken : null,
+					user,
+					isAuthenticated: true,
+				});
+			},
+
+			setTokens: (accessToken, refreshToken) => set({ accessToken, refreshToken }),
+
+			setUser: (user) => set({ user }),
+
+			setTenants: (tenants) => set({ tenants }),
+
+			setCurrentTenant: (tenantId) => set({ currentTenantId: tenantId }),
+
+			switchTenant: (tenantId) => set({ currentTenantId: tenantId }),
+
+			setPermissions: (permissions) => set({ permissions }),
+
+			clearAuth: () =>
+				set({
+					user: null,
+					accessToken: null,
+					refreshToken: null,
+					tenants: [],
+					currentTenantId: null,
+					permissions: [],
+					isAuthenticated: false,
+				}),
+		}),
+		{
+			name: 'autional-auth-v1',
+			version: 1,
+			// Custom merge: validate persisted data integrity before merging into store.
+			// This prevents corrupted localStorage entries from silently breaking auth.
+			merge: (persisted, current) => {
+				if (!persisted || typeof persisted !== 'object') return current;
+				const state = { ...current, ...persisted };
+
+				// Fix: has accessToken but isAuthenticated is false
+				if (state.accessToken && !state.isAuthenticated) {
+					state.isAuthenticated = true;
+				}
+				// Fix: no accessToken but isAuthenticated is true (token was evicted)
+				if (!state.accessToken && state.isAuthenticated) {
+					state.isAuthenticated = false;
+				}
+				// Fix: has accessToken but user is missing — recover from JWT
+				if (state.accessToken && !state.user) {
+					const payload = decodeJwtPayload(state.accessToken);
+					if (payload) {
+						state.user = {
+							id: (payload.sub || payload.user_id) as string,
+							username: ((payload.custom as Record<string, unknown> | undefined)?.username ||
+								payload.username) as string,
+							email: (payload.email as string) || '',
+							status: 'active',
+						};
+					}
+				}
+
+				return state;
+			},
+			migrate: (persisted) => {
+				// v0 → v1: no structural changes, data is compatible
+				return persisted as any;
+			},
+			partialize: (state) => {
+				return {
+					accessToken:
+						state.accessToken && state.accessToken !== 'undefined' && state.accessToken !== 'null'
+							? state.accessToken
+							: null,
+					refreshToken:
+						state.refreshToken &&
+						state.refreshToken !== 'undefined' &&
+						state.refreshToken !== 'null'
+							? state.refreshToken
+							: null,
+					user: state.user,
+					tenants: state.tenants,
+					currentTenantId: state.currentTenantId,
+					permissions: state.permissions,
+					isAuthenticated: state.isAuthenticated,
+				};
+			},
+			onRehydrateStorage: () => (state, error) => {
+				if (error || !state) return;
+				// merge already handles all fixups; this is a safety net
+				if (state.accessToken && !state.isAuthenticated) {
+					useAuthStore.setState({ isAuthenticated: true });
+				}
+			},
+		},
+	),
+);
+
+/**
+ * 获取 access token
+ */
+export function getAccessToken(): string | null {
+	const state = useAuthStore.getState().accessToken;
+	if (state && state !== 'undefined' && state !== 'null') return state;
+
+	return null;
+}
+
+/**
+ * 获取 refresh token
+ */
+export function getRefreshToken(): string | null {
+	const state = useAuthStore.getState().refreshToken;
+	if (state && state !== 'undefined' && state !== 'null') return state;
+	return null;
+}
+
+/**
+ * 获取当前租户 ID
+ */
+export function getCurrentTenantId(): string | null {
+	return useAuthStore.getState().currentTenantId;
+}
+
+/**
+ * 获取当前租户下的角色（userinfo-first，非响应式）
+ * 派生自 store.tenants + currentTenantId —— 不解析 token 载荷。
+ * 前端角色仅用于 UX 呈现；安全判断由后端 rbac-backed 授权强制（AC-008）。
+ */
+export function getCurrentRole(): string | null {
+	const { tenants, currentTenantId } = useAuthStore.getState();
+	if (!tenants || tenants.length === 0) return null;
+	if (!currentTenantId) return null;
+	return tenants.find((t) => t.id === currentTenantId)?.role ?? null;
+}
+
+/**
+ * 使用 token 登录（设置认证状态）
+ */
+export function loginWithTokens(
+	accessToken: string | null,
+	refreshToken: string | null,
+	user: User,
+): void {
+	useAuthStore.getState().setAuth(accessToken || '', refreshToken || '', user);
+}
+
+/**
+ * 退出登录（清除认证状态 + localStorage/cookie）
+ * 委托给 AuthService.logout() 统一实现
+ * 使用动态 import 避免 circular dependency (service.ts → store.ts)
+ *
+ * redirectTo（U350）：显式落点（会话过期→auth /error、注销完成→/<slug>/login?account_deleted=true 等
+ * 旗标页）——清理完成后整页前往。缺省仅清会话、不导航；注意与 useLogout 口径区分：该 hook 走
+ * buildLogoutUrl 登出意图流（logout=1 交入口路由定落点），不得用于需要保留业务 query 旗标的目标。
+ */
+export async function logout(redirectTo?: string): Promise<void> {
+	const { AuthService } = await import('./service');
+	await AuthService.logout();
+	if (redirectTo) {
+		traceRedirect(redirectTo, { reason: 'logout', assign: true });
+	}
+}
+
+export function isTokenExpired(token: string): boolean {
+	const payload = decodeJwtPayload(token);
+	const exp = payload?.exp as number | undefined;
+	if (!exp) return true;
+	return Date.now() >= exp * 1000;
+}
+
+export async function refreshAccessToken(): Promise<string | null> {
+	// 统一委托 AuthService.refreshToken()（含并发去重 + JWT/opaque 分流 + onUnauthorized 处理），
+	// 消除双实现：store 版不再持有重复的 refresh 逻辑（此前与 service 版不一致——无并发去重）。
+	// 动态 import 避免 store.ts ↔ service.ts 循环依赖。
+	const { AuthService } = await import('./service');
+	return AuthService.refreshToken();
+}

package/src/auth/tenant-route-middleware.ts

@@ -0,0 +1,113 @@
+/**
+ * useTenantRoute — 路由层中间件
+ *
+ * 从 URL slug 解析租户配置，与认证逻辑解耦。
+ * 代替 RequireAuth 直接使用 useOAuthClientIdFromUrl。
+ *
+ * 职责:
+ *  - 从 URL 提取 tenant slug
+ *  - 请求 OAuth 客户端配置 (slug → clientId)
+ *  - 自动将 tenantId 写入 AuthService
+ *  - 暴露 loading/notFound 状态给路由层
+ *
+ * @see docs/architecture/auth-next-issues-analysis.md
+ */
+
+'use client';
+
+import { useEffect } from 'react';
+import { useOAuthClientIdFromUrl } from './oauth-client-from-slug';
+import { AuthService } from './service';
+import { getPortalUrl } from '../config';
+
+export interface TenantRouteResult {
+	/** 租户 slug（从 URL 提取） */
+	slug: string | null;
+	/** 租户 ID（从 OAuth 配置获取） */
+	tenantId: string | null;
+	/** OAuth 客户端 ID */
+	oauthClientId: string | null;
+	/** 是否正在加载（API 请求中） */
+	loading: boolean;
+	/** 未找到（无 slug / 无 OAuth 配置 / slug 不存在） */
+	notFound: boolean;
+	/**
+	 * URL slug 确定性不存在（by-slug HTTP 404）。
+	 * 门户口径（F-W6）：本地渲染 404、不发弹跳 —— 否则与 auth 侧
+	 * 「有会话 → 回跳 redirect」构成无限整页往返。
+	 * 网络错误/5xx 不置本标记（fail-open，仍走原登录漏斗）。
+	 */
+	unknownSlug: boolean;
+}
+
+/**
+ * 路由层中间件：从 URL slug 解析租户配置。
+ *
+ * 用法:
+ * ```tsx
+ * function AppLayout() {
+ *   const tenantRoute = useTenantRoute();
+ *   if (tenantRoute.loading) return <Spin />;
+ *   return <App tenantSlug={tenantRoute.slug} />;
+ * }
+ * ```
+ */
+export function useTenantRoute(): TenantRouteResult {
+	const slugResolution = useOAuthClientIdFromUrl();
+
+	// Auto-store tenantId in AuthService when resolved
+	useEffect(() => {
+		if (slugResolution.status === 'resolved' && slugResolution.config.tenantId) {
+			AuthService.updateCurrentTenant(slugResolution.config.tenantId);
+		}
+	}, [slugResolution.status]);
+
+	// slug 在 useOAuthClientIdFromUrl 中通过 extractSlugFromPath 从 URL 提取，
+	// 通过 SlugResolution.resolved.slug 传递，无需从 API 响应中读取。
+	const slug = slugResolution.status === 'resolved' ? slugResolution.slug : null;
+
+	const unknownSlug = slugResolution.status === 'unknown-slug';
+
+	return {
+		slug,
+		tenantId: slugResolution.status === 'resolved' ? slugResolution.config.tenantId || null : null,
+		oauthClientId: slugResolution.status === 'resolved' ? slugResolution.clientId : null,
+		loading: slugResolution.status === 'loading',
+		notFound: slugResolution.status === 'not-found' || unknownSlug,
+		unknownSlug,
+	};
+}
+
+/**
+ * 获取有效的 OAuth clientId：配置 > 环境变量 > slug 解析。
+ * 这是 redirect 决策的核心逻辑，提取为纯函数便于测试。
+ */
+export function resolveEffectiveClientId(
+	tenantRoute: TenantRouteResult,
+	envClientId?: string,
+): string | null {
+	// slug 解析出的 clientId 优先（多租户场景）
+	if (tenantRoute.oauthClientId) return tenantRoute.oauthClientId;
+	// 环境变量其次（单租户/开发场景）
+	if (envClientId) return envClientId;
+	return null;
+}
+
+/**
+ * 判断 OAuth 是否在同域（slug-resolved 或同域 auth-pages）。
+ * SSR 安全：在服务端环境下始终返回 false。
+ */
+export function isSameDomainOAuth(tenantRoute: TenantRouteResult): boolean {
+	if (typeof window === 'undefined') return false; // SSR guard
+	if (tenantRoute.notFound) return false;
+	// slug 解析到的 client 一定是同域的（API 在同一 gateway 后）
+	if (tenantRoute.oauthClientId) return true;
+	// 检查 auth-pages URL 是否同域
+	try {
+		const authPagesUrl = getPortalUrl('auth');
+		if (!authPagesUrl) return false;
+		return new URL(authPagesUrl).origin === window.location.origin;
+	} catch {
+		return false;
+	}
+}

package/src/auth/tenant-slug-context.tsx

@@ -0,0 +1,9 @@
+import { createContext, useContext } from 'react';
+
+const TenantSlugContext = createContext<string | undefined>(undefined);
+
+export const TenantSlugProvider = TenantSlugContext.Provider;
+
+export function useTenantSlug(): string | undefined {
+	return useContext(TenantSlugContext);
+}

package/src/branding/BrandingInitializer.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useTenantSlugFromUrl } from '../auth/slug-from-url';
+import { tenantPublicTenantsByTenants } from '../generated/api';
+import { extractBranding } from './extract-branding';
+import { readCachedBranding, writeCachedBranding } from './branding-cache';
+import { useTenantBrandingStore } from './tenant-store';
+import type { Branding } from './types';
+
+const TTL = 6 * 60 * 60 * 1000; // 6h，与公开租户接口的缓存口径一致
+
+export interface BrandingInitializerProps {
+	/**
+	 * 覆盖 slug 来源。缺省按 URL 首段取（共享层口径）；
+	 * auth 站传入自己的判定——它要求至少两段，裸 /{slug} 视为无租户上下文。
+	 */
+	slug?: string | null;
+	/** 接口尚未返回时的兜底品牌（auth 站用 auth-config 里的 branding 段）。 */
+	fallback?: Branding | null;
+}
+
+/** 按 slug 拉公开品牌并写入 store；渲染 `null`，只做接线。 */
+export function BrandingInitializer({ slug: slugProp, fallback }: BrandingInitializerProps) {
+	const urlSlug = useTenantSlugFromUrl();
+	const slug = slugProp !== undefined ? slugProp : urlSlug;
+	const setBranding = useTenantBrandingStore((s) => s.setBranding);
+
+	// 缓存先到：首屏立即有品牌（未命中则由 useBranding 回落 tokens 缺省）
+	useEffect(() => {
+		if (!slug) {
+			setBranding(null);
+			return;
+		}
+		const cached = readCachedBranding(slug);
+		if (cached) setBranding(cached);
+	}, [slug, setBranding]);
+
+	const { data } = useQuery<Branding | null>({
+		queryKey: ['tenant-branding', slug],
+		queryFn: async () => {
+			if (!slug) return null;
+			const res = await tenantPublicTenantsByTenants(slug);
+			const branding = extractBranding(res);
+			if (branding) writeCachedBranding(slug, branding);
+			return branding;
+		},
+		enabled: Boolean(slug),
+		staleTime: TTL,
+		gcTime: TTL * 2,
+	});
+
+	useEffect(() => {
+		const resolved = data ?? fallback ?? null;
+		if (resolved) setBranding(resolved);
+	}, [data, fallback, setBranding]);
+
+	return null;
+}

package/src/branding/__tests__/brand-vars.test.ts

@@ -0,0 +1,126 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from 'vitest';
+import { applyBrandColors } from '../useBranding';
+import { hexToTriplet, deriveDarkColor, deriveTextColor } from '../brand-color';
+
+// U394 回归锁：品牌运行时注入必须同时写 `-rgb` 通道三元组。
+// 反证：删掉 useBranding 的 setColorVar 伴随行（只写 hex），本文件断言必须 FAIL——
+// 仅 hex 的品牌变量会让 Tailwind alpha 类（text-brand/60 → rgb(var(--color-brand-base-rgb)/0.6)）
+// 在品牌租户下解析不到通道，整条 alpha 色静默丢失。
+
+const ALL_VARS = [
+	'--color-brand-base',
+	'--color-brand-hover-base',
+	'--color-brand-dark',
+	'--color-brand-dark-hover',
+	'--color-brand-text-base',
+	'--color-on-brand-base',
+	'--color-on-brand',
+	'--color-on-brand-dark',
+];
+
+beforeEach(() => {
+	document.documentElement.removeAttribute('style');
+});
+
+describe('hexToTriplet', () => {
+	it('6 位 hex → 空格分隔三元组', () => {
+		expect(hexToTriplet('#003153')).toBe('0 49 83');
+		expect(hexToTriplet('#ffffff')).toBe('255 255 255');
+	});
+
+	it('3 位缩写与大写归一', () => {
+		expect(hexToTriplet('#123')).toBe('17 34 51');
+		expect(hexToTriplet('#FFBF00')).toBe('255 191 0');
+	});
+
+	it('非法输入 → null，不抛错（N3 防御）', () => {
+		expect(hexToTriplet('red')).toBeNull();
+		expect(hexToTriplet('#xyz')).toBeNull();
+		expect(hexToTriplet('')).toBeNull();
+	});
+});
+
+describe('applyBrandColors — -rgb 伴随写入', () => {
+	it('合法品牌色：7 个色变量各写 hex + 三元组', () => {
+		applyBrandColors('#003153');
+		const s = document.documentElement.style;
+		expect(s.getPropertyValue('--color-brand-base')).toBe('#003153');
+		expect(s.getPropertyValue('--color-brand-base-rgb')).toBe('0 49 83');
+		// AUTH-05：brand-base 白底 13.4:1 已达标 → 文本色原样；不达标色见 deriveTextColor 用例
+		expect(s.getPropertyValue('--color-brand-text-base')).toBe('#003153');
+		expect(s.getPropertyValue('--color-brand-text-base-rgb')).toBe('0 49 83');
+		expect(s.getPropertyValue('--color-brand-hover-base-rgb')).toBe('0 49 83');
+		expect(s.getPropertyValue('--color-brand-dark-rgb')).toBe(hexToTriplet(deriveDarkColor('#003153')));
+		expect(s.getPropertyValue('--color-brand-dark-hover-rgb')).not.toBe('');
+		expect(s.getPropertyValue('--color-on-brand-base-rgb')).toBe('255 255 255');
+		expect(s.getPropertyValue('--color-on-brand-dark-rgb')).not.toBe('');
+	});
+
+	it('darkOverride 生效时 base 与 dark 三元组各自独立', () => {
+		applyBrandColors('#003153', '#87ceeb');
+		const s = document.documentElement.style;
+		expect(s.getPropertyValue('--color-brand-base-rgb')).toBe('0 49 83');
+		expect(s.getPropertyValue('--color-brand-dark-rgb')).toBe('135 206 235');
+	});
+
+	it('清空（空串）：所有基础变量与 -rgb 伴随一并移除', () => {
+		applyBrandColors('#003153');
+		applyBrandColors('');
+		const s = document.documentElement.style;
+		for (const v of ALL_VARS) {
+			expect(s.getPropertyValue(v), v).toBe('');
+			expect(s.getPropertyValue(`${v}-rgb`), `${v}-rgb`).toBe('');
+		}
+	});
+
+	it('非 hex 值：写原值但移除 -rgb（不残留上一租户通道）', () => {
+		applyBrandColors('#003153');
+		applyBrandColors('red');
+		const s = document.documentElement.style;
+		expect(s.getPropertyValue('--color-brand-base')).toBe('red');
+		expect(s.getPropertyValue('--color-brand-base-rgb')).toBe('');
+	});
+});
+
+/** WCAG 2.x 对比度（测试内独立复算，锁 AUTH-05 派生结果对白底达标） */
+function contrastOnWhite(hex: string): number {
+	const d = hex.replace('#', '');
+	const [r, g, b] = [0, 2, 4].map((i) => parseInt(d.slice(i, i + 2), 16) / 255);
+	const lin = (c: number) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+	return 1.05 / (0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b) + 0.05);
+}
+
+describe('deriveTextColor — 浅底品牌文本色（AUTH-05）', () => {
+	it('#1890ff（白底 3.24:1 不达标）→ 压暗至 ≥4.5:1，且不等于原值', () => {
+		const out = deriveTextColor('#1890ff');
+		expect(out).not.toBe('#1890ff');
+		expect(contrastOnWhite(out)).toBeGreaterThanOrEqual(4.5);
+	});
+
+	it('达标输入原样返回（#003153 白底 ≈13.4:1）', () => {
+		expect(deriveTextColor('#003153')).toBe('#003153');
+	});
+
+	it('#ffffff → 必然压暗且达标', () => {
+		const out = deriveTextColor('#ffffff');
+		expect(out).not.toBe('#ffffff');
+		expect(contrastOnWhite(out)).toBeGreaterThanOrEqual(4.5);
+	});
+
+	it('非法输入 → 返回原值不抛错（N3 防御）', () => {
+		expect(deriveTextColor('red')).toBe('red');
+		expect(deriveTextColor('#xyz')).toBe('#xyz');
+		expect(deriveTextColor('')).toBe('');
+	});
+
+	it('applyBrandColors(#1890ff)：填充不变、文本另派生（AUTH-05 核心断言）', () => {
+		applyBrandColors('#1890ff');
+		const s = document.documentElement.style;
+		expect(s.getPropertyValue('--color-brand-base')).toBe('#1890ff');
+		const textBase = s.getPropertyValue('--color-brand-text-base');
+		expect(textBase).not.toBe('');
+		expect(textBase).not.toBe('#1890ff');
+		expect(contrastOnWhite(textBase)).toBeGreaterThanOrEqual(4.5);
+	});
+});