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

package/src/utils/__tests__/query-state.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from 'vitest';
+import {
+	classifyQueryState,
+	getHttpStatus,
+	isEmptyData,
+	isForbiddenError,
+	isRetryableError,
+} from '../query-state';
+
+// RC-B4-01（AC-B4-W0-01-2）：优先级矩阵硬序 forbidden > error > loading > empty > ready。
+// 关键不变式：error 存在时绝不回落 empty/ready；loading 且有旧数据 → ready。
+describe('classifyQueryState 优先级矩阵（AC-B4-W0-01-2）', () => {
+	const forbidden = () => ({ response: { status: 403 } });
+	const serverError = () => ({ response: { status: 500 } });
+	const networkError = () => new Error('Network Error');
+
+	it('forbidden 最高优先：403 时即使有 data/loading 仍判 forbidden', () => {
+		expect(classifyQueryState({ error: forbidden(), data: [1], isLoading: false })).toBe('forbidden');
+		expect(classifyQueryState({ error: forbidden(), isLoading: true })).toBe('forbidden');
+	});
+
+	it('error 存在时绝不回落 empty/ready（假 0 / 伪空态根因锁）', () => {
+		// error + 旧数据 → error（不因 data 有值回落 ready）
+		expect(classifyQueryState({ error: serverError(), data: [1] })).toBe('error');
+		// error + 空数组 → error（不回落 empty 伪装「暂无数据」）
+		expect(classifyQueryState({ error: networkError(), data: [] })).toBe('error');
+		// error + data undefined → error
+		expect(classifyQueryState({ error: networkError(), isLoading: false })).toBe('error');
+	});
+
+	it('error 优先于 loading', () => {
+		expect(classifyQueryState({ error: serverError(), isLoading: true })).toBe('error');
+	});
+
+	it('loading 且无旧数据 → loading', () => {
+		expect(classifyQueryState({ isLoading: true })).toBe('loading');
+		expect(classifyQueryState({ isLoading: true, data: [] })).toBe('loading');
+	});
+
+	it('loading 且有旧数据 → ready（stale 显示优先，不闪加载态）', () => {
+		expect(classifyQueryState({ isLoading: true, data: [1, 2] })).toBe('ready');
+	});
+
+	it('非 loading：空数据 → empty（null/undefined/[]）', () => {
+		expect(classifyQueryState({ data: [] })).toBe('empty');
+		expect(classifyQueryState({ data: null })).toBe('empty');
+		expect(classifyQueryState({})).toBe('empty');
+		expect(classifyQueryState({ isLoading: false })).toBe('empty');
+	});
+
+	it('有数据 → ready', () => {
+		expect(classifyQueryState({ data: [1] })).toBe('ready');
+		expect(classifyQueryState({ data: { total: 0 } })).toBe('ready');
+	});
+
+	it('无 error（null/undefined）不触发 error 分支', () => {
+		expect(classifyQueryState({ error: null, data: [1] })).toBe('ready');
+		expect(classifyQueryState({ error: undefined, data: [] })).toBe('empty');
+	});
+});
+
+// AC-B4-W0-01-3：isRetryable 矩阵（无 status/5xx/408/429 → true；4xx 业务错误 → false）。
+describe('isRetryableError 矩阵（AC-B4-W0-01-3）', () => {
+	it('无 status（网络/超时/未知）→ true', () => {
+		expect(isRetryableError(new Error('Network Error'))).toBe(true);
+		expect(isRetryableError({})).toBe(true);
+		expect(isRetryableError(undefined)).toBe(true);
+	});
+
+	it('5xx / 408 / 429 → true', () => {
+		expect(isRetryableError({ response: { status: 500 } })).toBe(true);
+		expect(isRetryableError({ response: { status: 502 } })).toBe(true);
+		expect(isRetryableError({ response: { status: 503 } })).toBe(true);
+		expect(isRetryableError({ response: { status: 408 } })).toBe(true);
+		expect(isRetryableError({ response: { status: 429 } })).toBe(true);
+	});
+
+	it('4xx 业务错误 → false（重试必败，不得给必败重试按钮）', () => {
+		for (const status of [400, 401, 403, 404, 409, 422]) {
+			expect(isRetryableError({ response: { status } })).toBe(false);
+		}
+	});
+});
+
+// getHttpStatus 形状兼容（axios 主形状 + fetch/自造形状）。
+describe('getHttpStatus 形状兼容', () => {
+	it('axios：response.status 优先', () => {
+		expect(getHttpStatus({ response: { status: 403 }, status: 500 })).toBe(403);
+	});
+
+	it('直挂 status / statusCode（fetch 及自造错误形状）', () => {
+		expect(getHttpStatus({ status: 404 })).toBe(404);
+		expect(getHttpStatus({ statusCode: 500 })).toBe(500);
+	});
+
+	it('非对象 / 无数字状态 → undefined', () => {
+		expect(getHttpStatus(undefined)).toBeUndefined();
+		expect(getHttpStatus(null)).toBeUndefined();
+		expect(getHttpStatus('boom')).toBeUndefined();
+		expect(getHttpStatus({ response: { status: '403' } })).toBeUndefined();
+	});
+});
+
+describe('isForbiddenError / isEmptyData 边界', () => {
+	it('isForbiddenError 只认 403（401 不在本分流）', () => {
+		expect(isForbiddenError({ response: { status: 403 } })).toBe(true);
+		expect(isForbiddenError({ response: { status: 401 } })).toBe(false);
+		expect(isForbiddenError({ response: { status: 500 } })).toBe(false);
+		expect(isForbiddenError(undefined)).toBe(false);
+	});
+
+	it('isEmptyData：null/undefined/[] → true；有元素/对象 → false', () => {
+		expect(isEmptyData(null)).toBe(true);
+		expect(isEmptyData(undefined)).toBe(true);
+		expect(isEmptyData([])).toBe(true);
+		expect(isEmptyData([1])).toBe(false);
+		expect(isEmptyData({})).toBe(false);
+		expect(isEmptyData(0)).toBe(false);
+	});
+});

package/src/utils/browser.ts

@@ -0,0 +1,15 @@
+// 返回值必须显式写成 Uint8Array<ArrayBuffer>：TS 5.7 起 TypedArray 带上了 buffer 的类型参数，
+// 裸写 Uint8Array 等于 Uint8Array<ArrayBufferLike>，而 PushManager.subscribe 要的是 BufferSource
+// （= ArrayBufferView<ArrayBuffer>）—— 于是 @autional/react 那边整包类型检查红着，
+// 而 shared 自己的项目里看不出来（两边 tsconfig 的解析路径不同）。实测踩到，见计划 L1。
+export function urlBase64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer> {
+	const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+	const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+	const rawData = window.atob(base64);
+	const bytes = Uint8Array.from(rawData.split('').map((c) => c.charCodeAt(0)));
+	// from() 的结果在类型上是 Uint8Array<ArrayBuffer>，这里显式复制到独立 ArrayBuffer
+	// 只是为了把「缓冲区归属」写死，避免将来换实现时又退回 ArrayBufferLike。
+	const out = new Uint8Array(new ArrayBuffer(bytes.length));
+	out.set(bytes);
+	return out;
+}

package/src/utils/case.ts

@@ -0,0 +1,59 @@
+/**
+ * 字段名大小写转换工具
+ * 后端 Go 返回 PascalCase，前端统一使用 camelCase
+ */
+
+import { camelCase, isPlainObject, isArray } from 'lodash-es';
+
+/**
+ * 递归将对象的所有键从 PascalCase/snake_case 转换为 camelCase
+ */
+export function camelCaseKeys<T>(obj: T): T {
+	if (isArray(obj)) {
+		return obj.map(camelCaseKeys) as unknown as T;
+	}
+	if (!isPlainObject(obj) || obj === null) {
+		return obj;
+	}
+
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+		result[camelCase(key)] = camelCaseKeys(value);
+	}
+	return result as T;
+}
+
+/**
+ * 单个键 camelCase → snake_case（acronym-aware）。
+ * U385：朴素正则（每个大写字母前插 `_`）会把缩写拆散——clientDataJSON →
+ * client_data_j_s_o_n、userID → user_i_d——WebAuthn 请求体（camel 书面键）经拦截器后
+ * 键名 mangling，服务端 go-webauthn 判为缺字段、校验恒败。两步修正：
+ *   ① 小写/数字 → 大写 边界插 `_`（aB → a_B）；
+ *   ② 连续大写后紧跟「大写+小写」时在缩写尾部插 `_`（JSONValue → JSON_Value）。
+ * 已是 snake 的字面量键（含下划线/无大写）两步均不命中，原样保留。
+ */
+function toSnakeKey(key: string): string {
+	return key
+		.replace(/([a-z\d])([A-Z])/g, '$1_$2')
+		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+		.toLowerCase();
+}
+
+/**
+ * 递归将对象的所有键从 camelCase 转换为 snake_case
+ * 用于发送请求到后端
+ */
+export function snakeCaseKeys<T>(obj: T): T {
+	if (isArray(obj)) {
+		return obj.map(snakeCaseKeys) as unknown as T;
+	}
+	if (!isPlainObject(obj) || obj === null) {
+		return obj;
+	}
+
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+		result[toSnakeKey(key)] = snakeCaseKeys(value);
+	}
+	return result as T;
+}

package/src/utils/error.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared error handling utilities
+ * Framework-agnostic: works with any UI notification system
+ */
+
+export interface ExtractedApiError {
+	code: number | string;
+	message: string;
+	/** AUTH-46：后端 Problem 契约的 i18n_key（如 error.oauth_state_invalid）。消费方可据此
+	 * 映射本地化文案；缺省时 undefined（message 键链不变，向后兼容）。 */
+	i18nKey?: string;
+}
+
+export function extractApiErrorMessage(err: unknown, defaultMsg: string): string {
+	return extractApiError(err, defaultMsg).message;
+}
+
+export function extractApiError(err: unknown, defaultMsg: string): ExtractedApiError {
+	// UP-17-B：后端 Problem 契约（service-core/base/dto/problem.go）字段为 title（必填）/ detail / code / i18n_key，
+	// **没有 message** —— 只认 message 会把整类后端错误退化成 defaultMsg。键链：message → title → detail → err.message。
+	// 继续用 `||`（而非 `??`）：空串语义按「缺省」处理，与既有实现一致。
+	// AUTH-46：附加透出 i18n_key（响应拦截器深 camel 后为 i18nKey，两者都认）。
+	const data = (err as any)?.response?.data;
+	return {
+		code: data?.code || 'UNKNOWN',
+		message: data?.message || data?.title || data?.detail || (err as any)?.message || defaultMsg,
+		i18nKey: data?.i18n_key || data?.i18nKey || undefined,
+	};
+}
+
+export function createHandleApiError(notify: (msg: string) => void) {
+	return (err: unknown, defaultMsg: string): void => {
+		notify(extractApiErrorMessage(err, defaultMsg));
+	};
+}

package/src/utils/format.ts

@@ -0,0 +1,63 @@
+let localeGetter: (() => string) | null = null;
+
+export function setLocaleGetter(fn: () => string) {
+	localeGetter = fn;
+}
+
+function getLocale(): string {
+	if (localeGetter) return localeGetter();
+	return 'zh-CN';
+}
+
+export function formatTime(iso: string | undefined | null, locale?: string): string {
+	if (!iso) return '--';
+	try {
+		const d = new Date(iso);
+		if (isNaN(d.getTime())) return iso;
+		return d.toLocaleString(locale || getLocale(), {
+			year: 'numeric',
+			month: '2-digit',
+			day: '2-digit',
+			hour: '2-digit',
+			minute: '2-digit',
+		});
+	} catch {
+		return iso;
+	}
+}
+
+export function formatDate(iso: string | undefined | null, locale?: string): string {
+	if (!iso) return '--';
+	try {
+		const d = new Date(iso);
+		if (isNaN(d.getTime())) return iso;
+		return d.toLocaleDateString(locale || getLocale(), {
+			year: 'numeric',
+			month: '2-digit',
+			day: '2-digit',
+		});
+	} catch {
+		return iso;
+	}
+}
+
+export function formatRelativeTime(iso: string | undefined | null, locale?: string): string {
+	if (!iso) return '--';
+	try {
+		const d = new Date(iso);
+		if (isNaN(d.getTime())) return iso;
+		const now = Date.now();
+		const diff = now - d.getTime();
+		const mins = Math.floor(diff / 60000);
+		const hours = Math.floor(diff / 3600000);
+		const days = Math.floor(diff / 86400000);
+
+		if (mins < 1) return 'just now';
+		if (mins < 60) return `${mins}m ago`;
+		if (hours < 24) return `${hours}h ago`;
+		if (days < 7) return `${days}d ago`;
+		return formatDate(iso, locale);
+	} catch {
+		return iso;
+	}
+}

package/src/utils/page.ts

@@ -0,0 +1,57 @@
+/**
+ * 分页/形状单点 helper（H008 收敛口径 · ADR-AB1-04）。
+ *
+ * 契约（与 `api/client.ts` 拦截器配对）：
+ * - 请求侧：页面传 camel 入参，`toPageParams` 输出 **snake**（`page` / `page_size`）；
+ *   拦截器再做一次深转换兜底，本函数保证键名口径单点。
+ * - 响应侧：拦截器已把 snake→camel 且解包信封；`fromPageResult` 是列表+分页的
+ *   唯一归一入口（内部复用 `extractList` / `extractPagination`），页面不得再写
+ *   `res?.data?.items ?? ...` 式手搓兼容。
+ */
+import { extractList, extractPagination } from './response';
+
+export interface PageParams {
+	page?: number;
+	page_size?: number;
+}
+
+export interface PageResult<T = Record<string, any>> {
+	items: T[];
+	total: number;
+	page: number;
+	page_size: number;
+}
+
+/** camel 分页入参 → 后端 snake 参数（pageSize 缺省不输出键；输出键集恰为 page/page_size）。 */
+export function toPageParams(input: { page?: number; pageSize?: number } = {}): PageParams {
+	const out: PageParams = {};
+	if (typeof input.page === 'number') out.page = input.page;
+	if (typeof input.pageSize === 'number') out.page_size = input.pageSize;
+	return out;
+}
+
+/**
+ * 响应归一：兼容三种输入——
+ * ① 扁平 `{ items, total, ... }`；② 信封 `{ data: { items, total } }`（拦截器未替换引用时的直读）；③ 裸数组。
+ * 裸数组的 total 取数组长度（唯一可知值）。
+ */
+export function fromPageResult<T = Record<string, any>>(resp: unknown): PageResult<T> {
+	const items = extractList<T>(resp);
+	const pagination = extractPagination(resp ?? {});
+	const r = (resp ?? {}) as Record<string, any>;
+	const dataObj = r.data as Record<string, any> | undefined;
+	const pickNum = (...vals: unknown[]): number | undefined => {
+		for (const v of vals) if (typeof v === 'number') return v;
+		return undefined;
+	};
+
+	return {
+		items,
+		total:
+			pickNum(r.total, dataObj?.total) ?? (Array.isArray(resp) ? items.length : pagination.total),
+		page: pickNum(r.page, dataObj?.page) ?? pagination.page,
+		page_size:
+			pickNum(r.page_size, r.pageSize, dataObj?.page_size, dataObj?.pageSize) ??
+			pagination.pageSize,
+	};
+}

package/src/utils/password-transmission.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createHash } from 'crypto';
+
+// SAME specifier string as source file's import ('../generated/api')
+vi.mock('../generated/api', () => ({
+	PublicKeyExchange: vi.fn(),
+}));
+
+import { processPasswordForTransmission } from './password-transmission';
+import { PublicKeyExchange as identityPublicKeyExchange } from '../generated/api';
+
+function sha256hex(input: string): string {
+	return createHash('sha256').update(input).digest('hex');
+}
+
+const TEST_PEM = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt4R4KXzLBZqHyQNqkLZA
+6h9YThQq4j+XdKmVF8vPq3HmLcDJ5FfTqM2kVxXCVmNJKHDbGzqP1WyvF5nTbgLV
+w8LkGd2pGHp3RKjCmJxLFHZVZyhWHt7aBPqMqMZGqkJFxD2cHqmNHyDCpHGkNs4b
+GqvBKPxcJnMkFEyFqFf7bSMCj1ARPbHHCq0vT9TmVwLPxkTVNpRjEGLWQzDqJGmF
+n9yIHxR5ckRLHkWKNvUPWyCkNQWHKtKvJWqKjqPpVtLRLHwNmyEYNYgWHPMfmjXZ
+dCqGNpLTHqJBYfCBGHJRFHYZQkFYi6LkUVhFqGxLkNLVNFPEKcZSMcKJqHmPQEtJ
+cQIDAQAB
+-----END PUBLIC KEY-----`;
+
+describe('processPasswordForTransmission', () => {
+	describe('plain mode', () => {
+		it('UT-TX-01: returns password unchanged with transmission=plain', async () => {
+			const result = await processPasswordForTransmission(
+				'Test@123',
+				'plain',
+				'acme-corp',
+				undefined,
+			);
+			expect(result.password).toBe('Test@123');
+			expect(result.passwordTransmission).toBe('plain');
+		});
+	});
+
+	describe('hash mode', () => {
+		it('UT-TX-02: returns SHA-256 hex of password|tenantId', async () => {
+			const result = await processPasswordForTransmission(
+				'Test@123',
+				'hash',
+				'acme-corp',
+				undefined,
+			);
+			const expected = sha256hex('Test@123|acme-corp');
+			expect(result.password).toBe(expected);
+			expect(result.passwordTransmission).toBe('hash');
+		});
+
+		it('UT-TX-03: handles empty tenantId', async () => {
+			const result = await processPasswordForTransmission('Test@123', 'hash', '', undefined);
+			const expected = sha256hex('Test@123|');
+			expect(result.password).toBe(expected);
+		});
+
+		it('UT-TX-04: handles chinese characters', async () => {
+			const result = await processPasswordForTransmission(
+				'测试@123',
+				'hash',
+				'acme-corp',
+				undefined,
+			);
+			const expected = sha256hex('测试@123|acme-corp');
+			expect(result.password).toBe(expected);
+			expect(result.passwordTransmission).toBe('hash');
+		});
+	});
+
+	describe('undefined / default mode', () => {
+		it('UT-TX-05: throws when mode is undefined (no silent plain fallback)', async () => {
+			await expect(
+				processPasswordForTransmission('Test@123', undefined, 'acme-corp', undefined),
+			).rejects.toThrow('password transmission mode is missing from tenant auth-config');
+		});
+
+		it('UT-TX-05b: throws when mode is empty string', async () => {
+			await expect(
+				processPasswordForTransmission('Test@123', '', 'acme-corp', undefined),
+			).rejects.toThrow('password transmission mode is missing from tenant auth-config');
+		});
+	});
+
+	describe('symmetric mode', () => {
+		const mockServerPubKey =
+			'BDmXBCDz0nrP5sHAh7ahMBjiIPIqg1lEHfXzw434ChYa/scxqUzjV4vFzw0jFzpKVhvhgIW62xdHKppccUa7sic=';
+
+		// jsdom limitation: crypto.subtle ECDH P-256 raw key import not supported.
+		// The symmetric encryption logic is verified at the Go level:
+		//   seed/tool/crypto_test.go — TestSymmetricEncrypt_RoundTrip PASS
+		// The mock interception is verified by UT-TX-07 (rejection case).
+		it.skip('UT-TX-06: returns ciphertext with keyExchangeId (skipped — jsdom crypto.subtle lacks ECDH raw import)', async () => {
+			(identityPublicKeyExchange as unknown as ReturnType<typeof vi.fn>).mockImplementation(() =>
+				Promise.resolve({ serverPubKey: mockServerPubKey, keyExchangeId: 'test-exchange-1' }),
+			);
+			try {
+				const result = await processPasswordForTransmission(
+					'Test@123',
+					'symmetric',
+					'acme-corp',
+					undefined,
+				);
+				expect(result.passwordTransmission).toBe('symmetric');
+				expect(result.password).toBeTruthy();
+				expect(typeof result.password).toBe('string');
+				expect(result.keyExchangeId).toBe('test-exchange-1');
+				expect(result.clientPubKey).toBeTruthy();
+			} catch (e) {
+				console.error('SYMMETRIC FAILED:', e);
+				throw e;
+			}
+		});
+
+		it('UT-TX-07: throws when keyExchange fails', async () => {
+			vi.mocked(identityPublicKeyExchange).mockRejectedValueOnce(new Error('Network error'));
+
+			await expect(
+				processPasswordForTransmission('Test@123', 'symmetric', 'acme-corp', undefined),
+			).rejects.toThrow();
+		});
+	});
+
+	describe('asymmetric mode', () => {
+		it('UT-TX-08: returns RSA-OAEP ciphertext', async () => {
+			const result = await processPasswordForTransmission(
+				'Test@123',
+				'asymmetric',
+				'acme-corp',
+				TEST_PEM,
+			);
+
+			expect(result.passwordTransmission).toBe('asymmetric');
+			expect(result.password).toBeTruthy();
+			expect(typeof result.password).toBe('string');
+		});
+
+		it('UT-TX-09: throws when publicKey is missing', async () => {
+			await expect(
+				processPasswordForTransmission('Test@123', 'asymmetric', 'acme-corp', undefined),
+			).rejects.toThrow();
+		});
+	});
+});