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

package/src/api/client.ts

@@ -0,0 +1,191 @@
+/**
+ * Autional 统一 API Client
+ * - 所有前端应用共用同一个 axios 实例
+ * - 自动注入 Bearer token + X-Tenant-ID
+ * - 自动 unwrap 后端响应 + PascalCase→camelCase 转换
+ * - 自动 token refresh + 401 处理
+ */
+
+import axios, { AxiosError } from 'axios';
+import type { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
+import { camelCaseKeys, snakeCaseKeys } from '../utils/case';
+import { API_NAMESPACE, getApiBaseUrl } from '../config';
+import { getTraceParentHeader } from './trace';
+import { ENTRY_PLANE_HEADER, resolveEntryPlane } from './entry-plane';
+import { NAMESPACE_HEADER, needsNamespaceHeader } from './namespace';
+import { AuthService } from '../auth/service';
+
+function setupInterceptors(instance: AxiosInstance) {
+	// ============ Request Interceptor ============
+	instance.interceptors.request.use(async (config: InternalAxiosRequestConfig) => {
+		// 预判式 Token 刷新：如果 Token 已过期或即将过期（60s 缓冲），先刷新再发请求
+		// U352：刷新成功只替换本次 bearer —— 不得提前 return，否则跳过后方全部注入
+		// （X-Tenant-ID / namespace / body·params snakeCase / entry-plane / traceparent）。
+		const token = AuthService.getAccessToken();
+		let bearer = token;
+		if (token && AuthService.isTokenExpired(token)) {
+			try {
+				const newToken = await AuthService.refreshToken();
+				if (newToken) bearer = newToken;
+			} catch (e) {
+				console.warn('[API] token pre-refresh failed', (e as Error)?.message || '');
+			}
+		}
+		if (bearer) {
+			config.headers.Authorization = `Bearer ${bearer}`;
+		}
+
+		const tenantId = AuthService.getCurrentTenantId();
+		if (tenantId) {
+			config.headers['X-Tenant-ID'] = tenantId;
+		}
+
+		// secret 管理面（§13-A P1-B）：admin 组端点 fail-closed 要求 X-Namespace ∈ S
+		if (needsNamespaceHeader(config.url)) {
+			config.headers[NAMESPACE_HEADER] = API_NAMESPACE;
+		}
+
+		// 请求体 camelCase → snake_case 转换（后端 Go 期望 snake_case）
+		// 【契约指针】请求参数/体构造一律用 camel 书面写，键名转换由本拦截器承担；
+		// 分页参数请经 shared `toPageParams`（utils/page.ts）构造，勿手写 snake 键字面量。
+		if (config.data && typeof config.data === 'object' && !(config.data instanceof FormData)) {
+			config.data = snakeCaseKeys(config.data);
+		}
+
+		// 查询参数 camelCase → snake_case 转换（后端 Go 期望 snake_case form tag）
+		if (config.params && typeof config.params === 'object') {
+			config.params = snakeCaseKeys(config.params);
+		}
+
+		// 按入口登录（P5）：登录端点声明入口平面，identity 据此签发 entry_plane claim
+		// （admin./platform. 门户的 redirect 目标决定平面；缺省 api）
+		if (config.url?.includes('/api/v1/auth/login') && typeof window !== 'undefined') {
+			const redirect = new URLSearchParams(window.location.search).get('redirect');
+			config.headers[ENTRY_PLANE_HEADER] = resolveEntryPlane(redirect, window.location.hostname);
+		}
+
+		const traceparent = getTraceParentHeader();
+		if (traceparent) {
+			config.headers['traceparent'] = traceparent;
+		}
+
+		return config;
+	});
+
+	// ============ Response Interceptor ============
+	instance.interceptors.response.use(
+		(res) => {
+			const data = res.data;
+
+			// 只处理后端标准响应格式 { code, message, ... }
+			if (data && typeof data === 'object' && 'code' in data) {
+				let payload: unknown;
+
+				// 嵌套 data 格式: { code, message, data: {...}, timestamp }
+				if ('data' in data && data.data !== undefined) {
+					payload = data.data;
+				}
+				// 扁平列表格式: { code, message, items, total, pagination, timestamp }
+				else if ('items' in data) {
+					payload = {
+						items: data.items,
+						total: data.total,
+						pagination: data.pagination,
+					};
+				}
+				// 无 data/items 的简单响应 (如删除成功)
+				else {
+					payload = data;
+				}
+
+				// PascalCase → camelCase 转换
+				// 【契约指针】响应键名转换单点在拦截器；页面读取形状请用
+				// `extractList` / `extractItem`（唯一形状适配点，utils/response.ts），
+				// 分页归一用 `fromPageResult`（utils/page.ts）——勿在页面里手写转换/解包。
+				res.data = camelCaseKeys(payload);
+			}
+
+			return res;
+		},
+		async (err: AxiosError) => {
+			const originalRequest = err.config as InternalAxiosRequestConfig & {
+				_retry?: boolean;
+				_tenantRetry?: boolean;
+			};
+			if (!originalRequest) return Promise.reject(err);
+
+			// 401 → token refresh (skip for login & refresh endpoints — no token to refresh / avoid loops)
+			// Also skip OAuth token-exchange: a 401 there is a business error (invalid_grant / invalid_client),
+			// NOT session expiry. Treating it as one routes through refreshToken() → onUnauthorized → login
+			// page bounce while the auth code is already consumed → infinite redirect loop.
+			if (
+				err.response?.status === 401 &&
+				!originalRequest._retry &&
+				!originalRequest.url?.includes('/api/v1/auth/login') &&
+				!originalRequest.url?.includes('/api/v1/auth/refresh') &&
+				!originalRequest.url?.includes('/oauth/api/v1/oauth/token') &&
+				// oauth refresh 端点自身的 401（无效/过期 refresh token）是业务性失败，
+				// 不走 refresh 重试（避免 oauth refresh → 401 → 再 refresh 的循环）
+				!originalRequest.url?.includes('/oauth/api/v1/oauth/refresh') &&
+				// P1-4: export-data 的业务性 401（step-up 拒绝）不是会话过期，
+				// 不走 refresh 重试/登出，由页面 catch 展示错误。
+				!originalRequest.url?.includes('/auth/me/export-data') &&
+				// AUTH-42: delete-account 的 401 是业务性失败（step-up 缺失/过期 40800251、
+				// 密码错误 40000502），不是会话过期；走 refresh 重试会掩盖真因（审计现场
+				// 即 401→refresh 200→重试 401 双跳后误报「请检查密码是否正确」）。
+				!originalRequest.url?.includes('/auth/me/delete-account') &&
+				// re-authenticate 同理：密码错误 401（40000502）须由页面按 code 分流文案。
+				!originalRequest.url?.includes('/auth/re-authenticate')
+			) {
+				originalRequest._retry = true;
+
+				// 尝试刷新 token（refreshToken 内部处理无 refresh token / 刷新失败 / onUnauthorized）
+				const newToken = await AuthService.refreshToken();
+				if (newToken) {
+					originalRequest.headers.Authorization = `Bearer ${newToken}`;
+					return instance(originalRequest);
+				}
+
+				// 刷新失败 → 已由 refreshToken 内部调用 onUnauthorized
+				return Promise.reject(err);
+			}
+
+			// 404 + tenant not found (ErrCodeDomainTenantNotFound=40000102)
+			// → clear tenant from store → retry without X-Tenant-ID
+			const data = err.response?.data as any;
+			if (
+				err.response?.status === 404 &&
+				data?.code === '40000102' &&
+				!originalRequest._tenantRetry
+			) {
+				originalRequest._tenantRetry = true;
+				AuthService.updateCurrentTenant('');
+				// Remove X-Tenant-ID header and retry
+				const headers = originalRequest.headers as Record<string, unknown>;
+				delete headers['X-Tenant-ID'];
+				return instance(originalRequest);
+			}
+
+			return Promise.reject(err);
+		},
+	);
+}
+
+/**
+ * 创建自定义 baseURL 的 API client 实例
+ * 适用于需要访问多个不同服务前缀的场景（如 admin-console）
+ */
+export function createApiClient(baseUrl: string): AxiosInstance {
+	const instance = axios.create({
+		baseURL: baseUrl,
+		timeout: 30000,
+		headers: { 'Content-Type': 'application/json' },
+	});
+	setupInterceptors(instance);
+	return instance;
+}
+
+/**
+ * 默认 API client 实例，baseURL 从 API_BASE_URL 配置读取，fallback '/api/v1'
+ */
+export const apiClient: AxiosInstance = createApiClient(getApiBaseUrl());

package/src/api/entry-plane.ts

@@ -0,0 +1,61 @@
+/**
+ * 按入口登录：登录请求的入口平面声明（GATEWAY-ENTRY-ISOLATION-DESIGN §4.4）。
+ * 值域 api|admin|platform（identity entry_plane.go 契约）；仅登录端点消费，
+ * refresh/challenge 由服务端从 claim 继承，无需前端声明。
+ */
+
+export type EntryPlane = 'api' | 'admin' | 'platform';
+
+export const ENTRY_PLANE_HEADER = 'X-Entry-Plane';
+
+function planeFromHostname(hostname: string): EntryPlane | null {
+	const h = hostname.toLowerCase();
+	if (h === 'admin' || h.startsWith('admin.')) return 'admin';
+	// security.<root>（安全仪表盘/SOC 门户）API 面为 admin 受众（风险看板等 admin 路由），
+	// 与 admin 门户同平面（GATEWAY-ENTRY-ISOLATION-DESIGN §3.2/§4.4）。
+	if (h === 'security' || h.startsWith('security.')) return 'admin';
+	if (h === 'platform' || h.startsWith('platform.')) return 'platform';
+	return null;
+}
+
+/**
+ * 授权流下钻：同意页冷启动时（无会话），登录页的 redirect 参数是 authorize URL 本身
+ * （`<slug>/login?redirect=<authorize URL>`，oauth-cold-start/TASK-07），其宿主是 auth
+ * 门户 ⇒ 宿主判定为空。发起门户嵌在其查询参数里：`redirect_uri`（发起方回调，宿主即
+ * 门户）或 `state.redirect`（发起页 URL，见 oauth-login state 载荷）。不下钻则回程
+ * 门户拿到的 token 平面恒为 api，admin/platform 受众端点全部 403 40000503（F-W5）。
+ */
+function planeFromAuthorizeRequest(url: URL): EntryPlane | null {
+	if (!url.pathname.includes('/oauth/authorize')) return null;
+	const candidates: Array<string | null> = [url.searchParams.get('redirect_uri')];
+	try {
+		const state = JSON.parse(url.searchParams.get('state') || '');
+		if (state && typeof state.redirect === 'string') candidates.push(state.redirect);
+	} catch {
+		// state 非 JSON（旧式纯串）→ 唯一候选 redirect_uri
+	}
+	for (const candidate of candidates) {
+		if (!candidate) continue;
+		try {
+			const plane = planeFromHostname(new URL(candidate, url.origin).hostname);
+			if (plane) return plane;
+		} catch {
+			// 单个候选非法不阻断后续候选
+		}
+	}
+	return null;
+}
+
+/** 由登录页 redirect 参数目标（或当前主机）推导入口平面，无法判定时缺省 api。 */
+export function resolveEntryPlane(redirect: string | null, currentHostname: string): EntryPlane {
+	if (redirect) {
+		try {
+			const url = new URL(redirect, `https://${currentHostname || 'localhost'}`);
+			const fromTarget = planeFromHostname(url.hostname) ?? planeFromAuthorizeRequest(url);
+			if (fromTarget) return fromTarget;
+		} catch {
+			// redirect 非法时回落当前主机判定
+		}
+	}
+	return planeFromHostname(currentHostname) ?? 'api';
+}

package/src/api/namespace.ts

@@ -0,0 +1,14 @@
+/**
+ * secret 服务管理面 namespace（§13-A P1-B / SEC-204/207）：
+ * `/secret/api/v1/admin*` 端点 fail-closed 要求 `X-Namespace ∈ 实例服务集合 S`
+ * （NamespaceMiddleware，缺头/未服务 → 400）。值取部署配置 VITE_API_NAMESPACE
+ * （见 config，缺省 "dev" 与服务端 DefaultNamespace 对称）。
+ */
+
+export const NAMESPACE_HEADER = 'X-Namespace';
+
+export const SECRET_ADMIN_PATH_PREFIX = '/secret/api/v1/admin';
+
+export function needsNamespaceHeader(url?: string): boolean {
+	return !!url && url.includes(SECRET_ADMIN_PATH_PREFIX);
+}

package/src/api/trace.ts

@@ -0,0 +1,21 @@
+const traceparentProviders: Array<() => string | undefined> = [];
+
+export function setTraceParentProvider(provider: () => string | undefined): void {
+	traceparentProviders.push(provider);
+}
+
+export function getTraceParentHeader(): string | undefined {
+	for (const provider of traceparentProviders) {
+		const tp = provider();
+		if (tp) return tp;
+	}
+	return undefined;
+}
+
+export function resetSessionTraceId(): void {
+	// trace ID is managed by the OTel bridge
+}
+
+export function enableOtelBridge(): void {
+	// No-op stub — requires @opentelemetry/api dependency
+}

package/src/auth/__tests__/ac007-role-source.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { useAuthStore, getCurrentRole } from '../store';
+
+// 注：node 测试环境下 zustand persist 中间件会打印一条无害的 storage 降级警告
+// （"Unable to update item 'autional-auth-v1'"），这是 store.ts 既有 persist 的
+// 标准降级行为，不影响被测的 getCurrentRole 派生逻辑。
+
+const TENANTS = [
+	{ id: 'tenant-a', name: 'Tenant A', role: 'admin' },
+	{ id: 'tenant-b', name: 'Tenant B', role: 'member' },
+];
+
+/**
+ * 构造最小 JWT（base64url header.payload.signature）。
+ * 仅用于测试「前端不再读取 token 载荷」——getCurrentRole 只读 store，
+ * 因此 signature 内容无关紧要。
+ */
+function buildJwt(payload: Record<string, unknown>): string {
+	const enc = (obj: unknown) =>
+		btoa(JSON.stringify(obj)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+	return `${enc({ alg: 'none', typ: 'JWT' })}.${enc(payload)}.test-signature`;
+}
+
+/** 重置 store 到初始状态，避免跨用例污染 */
+function resetAuthStore(): void {
+	useAuthStore.setState({
+		user: null,
+		accessToken: null,
+		refreshToken: null,
+		tenants: [],
+		currentTenantId: null,
+		permissions: [],
+		isAuthenticated: false,
+	});
+}
+
+describe('AC-007 密码/OAuth 双路径行为一致（userinfo-first，角色来自 store）', () => {
+	beforeEach(() => {
+		resetAuthStore();
+	});
+
+	it('密码场景：token 带 custom.role 但前端不读 → 返回 store 角色', () => {
+		// 密码登录 token 载荷带 custom.role（旧解析来源），但前端已不再读取
+		const passwordToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'super_admin', username: 'pw-user' },
+		});
+
+		// 角色真正来源：loadAuthExtras 写入的 store
+		useAuthStore.setState({
+			accessToken: passwordToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+
+		// 若前端仍解析 token 会得到 super_admin；正确行为是返回 store 角色 admin
+		expect(getCurrentRole()).toBe('admin');
+	});
+
+	it('OAuth 场景：token 无 role + 相同 store → 结果与密码场景一致', () => {
+		// OAuth/挂载路径 token 载荷无 role（旧解析无角色来源）
+		const oauthToken = buildJwt({ sub: 'user-1' });
+
+		useAuthStore.setState({
+			accessToken: oauthToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+
+		expect(getCurrentRole()).toBe('admin');
+	});
+
+	it('双路径矩阵：两场景结果相等（store 预填充为唯一角色来源）', () => {
+		const passwordToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'super_admin', username: 'pw-user' },
+		});
+		const oauthToken = buildJwt({ sub: 'user-1' });
+
+		// 相同 store 预填充
+		useAuthStore.setState({
+			accessToken: passwordToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		const roleFromPassword = getCurrentRole();
+
+		useAuthStore.setState({
+			accessToken: oauthToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		const roleFromOAuth = getCurrentRole();
+
+		expect(roleFromPassword).toBe(roleFromOAuth);
+		expect(roleFromPassword).toBe('admin');
+		expect(roleFromOAuth).toBe('admin');
+	});
+
+	it('token 携带不同 custom.role 时 store 角色仍胜出（证明零 token 载荷读取）', () => {
+		const adminToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'super_admin' },
+		});
+		const memberToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'member' },
+		});
+
+		useAuthStore.setState({
+			accessToken: adminToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		expect(getCurrentRole()).toBe('admin'); // store 角色，非 token 的 super_admin
+
+		useAuthStore.setState({
+			accessToken: memberToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		expect(getCurrentRole()).toBe('admin'); // token role 变化不影响 store 派生
+	});
+});

package/src/auth/__tests__/auth-machine.test.ts

@@ -0,0 +1,157 @@
+/**
+ * AuthMachine 单元测试
+ *
+ * 验证状态机 reducer 的纯函数逻辑:
+ * - 状态转换是否正确
+ * - 边界条件
+ * - 从不合法状态恢复
+ */
+import { describe, it, expect } from 'vitest';
+
+// AuthMachine 的 reducer 逻辑是纯函数，可以直接测试
+type AuthStatus =
+	| 'checking'
+	| 'authenticated'
+	| 'bootstrap'
+	| 'ready'
+	| 'unauthenticated'
+	| 'redirecting';
+
+interface MachineState {
+	status: AuthStatus;
+	hasToken: boolean;
+}
+
+type Action =
+	| { type: 'TOKEN_FOUND' }
+	| { type: 'NO_TOKEN' }
+	| { type: 'BOOTSTRAP_LOADING' }
+	| { type: 'BOOTSTRAP_READY' }
+	| { type: 'BOOTSTRAP_ERROR' }
+	| { type: 'SESSION_EXPIRED' }
+	| { type: 'REDIRECT' };
+
+function authReducer(state: MachineState, action: Action): MachineState {
+	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 === 'authenticated'
+				? { ...state, status: 'ready' }
+				: state;
+		case 'BOOTSTRAP_ERROR':
+			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;
+	}
+}
+
+function createInitialState(): MachineState {
+	return { status: 'checking', hasToken: false };
+}
+
+describe('AuthMachine reducer', () => {
+	it('初始状态为 checking，无 token', () => {
+		const state = createInitialState();
+		expect(state.status).toBe('checking');
+		expect(state.hasToken).toBe(false);
+	});
+
+	it('TOKEN_FOUND → authenticated', () => {
+		const state = authReducer(createInitialState(), { type: 'TOKEN_FOUND' });
+		expect(state.status).toBe('authenticated');
+		expect(state.hasToken).toBe(true);
+	});
+
+	it('NO_TOKEN → unauthenticated', () => {
+		const state = authReducer(createInitialState(), { type: 'NO_TOKEN' });
+		expect(state.status).toBe('unauthenticated');
+		expect(state.hasToken).toBe(false);
+	});
+
+	it('authenticated + BOOTSTRAP_LOADING → bootstrap', () => {
+		const authenticated = authReducer(createInitialState(), { type: 'TOKEN_FOUND' });
+		const state = authReducer(authenticated, { type: 'BOOTSTRAP_LOADING' });
+		expect(state.status).toBe('bootstrap');
+	});
+
+	it('authenticated + BOOTSTRAP_READY → ready（跳过 bootstrap）', () => {
+		const authenticated = authReducer(createInitialState(), { type: 'TOKEN_FOUND' });
+		const state = authReducer(authenticated, { type: 'BOOTSTRAP_READY' });
+		expect(state.status).toBe('ready');
+	});
+
+	it('bootstrap + BOOTSTRAP_READY → ready', () => {
+		const authenticated = authReducer(createInitialState(), { type: 'TOKEN_FOUND' });
+		const bootstrap = authReducer(authenticated, { type: 'BOOTSTRAP_LOADING' });
+		const state = authReducer(bootstrap, { type: 'BOOTSTRAP_READY' });
+		expect(state.status).toBe('ready');
+	});
+
+	it('bootstrap + BOOTSTRAP_ERROR → ready（降级运行）', () => {
+		const authenticated = authReducer(createInitialState(), { type: 'TOKEN_FOUND' });
+		const bootstrap = authReducer(authenticated, { type: 'BOOTSTRAP_LOADING' });
+		const state = authReducer(bootstrap, { type: 'BOOTSTRAP_ERROR' });
+		expect(state.status).toBe('ready');
+	});
+
+	it('SESSION_EXPIRED → unauthenticated（从任何状态）', () => {
+		const ready = authReducer(
+			authReducer(authReducer(createInitialState(), { type: 'TOKEN_FOUND' }), {
+				type: 'BOOTSTRAP_READY',
+			}),
+			{ type: 'SESSION_EXPIRED' },
+		);
+		expect(ready.status).toBe('unauthenticated');
+		expect(ready.hasToken).toBe(false);
+	});
+
+	it('unauthenticated + REDIRECT → redirecting', () => {
+		const unauth = authReducer(createInitialState(), { type: 'NO_TOKEN' });
+		const state = authReducer(unauth, { type: 'REDIRECT' });
+		expect(state.status).toBe('redirecting');
+	});
+
+	it('checking 态下 BOOTSTRAP_LOADING 不应改变状态', () => {
+		const state = authReducer(createInitialState(), { type: 'BOOTSTRAP_LOADING' });
+		expect(state.status).toBe('checking'); // 不变
+	});
+
+	it('checking 态下 BOOTSTRAP_READY 不应改变状态', () => {
+		const state = authReducer(createInitialState(), { type: 'BOOTSTRAP_READY' });
+		expect(state.status).toBe('checking'); // 不变
+	});
+
+	it('完整 happy path: checking → authenticated → bootstrap → ready', () => {
+		let state = createInitialState();
+		expect(state.status).toBe('checking');
+
+		state = authReducer(state, { type: 'TOKEN_FOUND' });
+		expect(state.status).toBe('authenticated');
+
+		state = authReducer(state, { type: 'BOOTSTRAP_LOADING' });
+		expect(state.status).toBe('bootstrap');
+
+		state = authReducer(state, { type: 'BOOTSTRAP_READY' });
+		expect(state.status).toBe('ready');
+	});
+
+	it('完整 unauthenticated path: checking → unauthenticated → redirecting', () => {
+		let state = createInitialState();
+		expect(state.status).toBe('checking');
+
+		state = authReducer(state, { type: 'NO_TOKEN' });
+		expect(state.status).toBe('unauthenticated');
+
+		state = authReducer(state, { type: 'REDIRECT' });
+		expect(state.status).toBe('redirecting');
+	});
+});