@h-ai/kit 0.1.0-alpha.67 → 0.1.0-alpha.68

package/dist/kit-crypto-types-Dd24aJ4m.d.ts

@@ -0,0 +1,194 @@
+import { TransportServerKeyRing, CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
+import { RequestEvent } from '@sveltejs/kit';
+
+/**
+ * @h-ai/kit — Crypto 类型定义
+ *
+ * Crypto 模块集成相关类型
+ * @module kit-crypto-types
+ */
+
+/**
+ * 辅助函数所需的异步加密依赖结构；实际服务需由应用适配，不等同于 @h-ai/crypto 的公开接口。
+ * @example
+ * ```ts
+ * import type { CryptoServiceLike } from '@h-ai/kit'
+ *
+ * async function verify(crypto: CryptoServiceLike, body: string, secret: string, signature: string) {
+ *   const result = await crypto.hmac.verify(body, secret, signature, 'sha256')
+ *   return result.success && result.data === true
+ * }
+ * ```
+ */
+interface CryptoServiceLike {
+    hmac: {
+        sign: (data: string, key: string, algorithm?: string) => Promise<{
+            success: boolean;
+            data?: string;
+            error?: {
+                code: number;
+                message: string;
+            };
+        }>;
+        verify: (data: string, key: string, signature: string, algorithm?: string) => Promise<{
+            success: boolean;
+            data?: boolean;
+            error?: {
+                code: number;
+                message: string;
+            };
+        }>;
+    };
+    hash: {
+        digest: (data: string, algorithm?: string) => Promise<{
+            success: boolean;
+            data?: string;
+            error?: {
+                code: number;
+                message: string;
+            };
+        }>;
+        timingSafeEqual: (a: string, b: string) => Promise<{
+            success: boolean;
+            data?: boolean;
+            error?: {
+                code: number;
+                message: string;
+            };
+        }>;
+    };
+    aes: {
+        encrypt: (data: string, key: string) => Promise<{
+            success: boolean;
+            data?: string;
+            error?: {
+                code: number;
+                message: string;
+            };
+        }>;
+        decrypt: (data: string, key: string) => Promise<{
+            success: boolean;
+            data?: string;
+            error?: {
+                code: number;
+                message: string;
+            };
+        }>;
+    };
+    random: {
+        bytes: (length: number) => Promise<{
+            success: boolean;
+            data?: Uint8Array;
+            error?: {
+                code: number;
+                message: string;
+            };
+        }>;
+    };
+}
+/**
+ * Webhook 验证配置
+ * @example
+ * ```ts
+ * import type { WebhookVerifyConfig } from '@h-ai/kit'
+ *
+ * function signatureHeader(config: WebhookVerifyConfig) { return config.event.request.headers.get(config.signatureHeader ?? 'X-Signature') }
+ * ```
+ */
+interface WebhookVerifyConfig {
+    /** Crypto 服务实例 */
+    crypto: CryptoServiceLike;
+    /** 请求事件 */
+    event: RequestEvent;
+    /** 签名密钥 */
+    secretKey: string;
+    /** 签名头名称 */
+    signatureHeader?: string;
+    /** 算法 */
+    algorithm?: 'sha256' | 'sha512';
+    /** 编码 */
+    encoding?: 'hex' | 'base64';
+}
+/**
+ * CSRF 配置
+ * @example
+ * ```ts
+ * import type { CryptoCsrfConfig } from '@h-ai/kit'
+ *
+ * function tokenSize(config: CryptoCsrfConfig) { return config.tokenLength ?? 32 }
+ * ```
+ */
+interface CryptoCsrfConfig {
+    /** Crypto 服务实例 */
+    crypto: CryptoServiceLike;
+    /** Cookie 名称 */
+    cookieName?: string;
+    /** Header 名称 */
+    headerName?: string;
+    /** 表单字段名称 */
+    formFieldName?: string;
+    /** Token 长度 */
+    tokenLength?: number;
+    /** Cookie 选项 */
+    cookieOptions?: {
+        path?: string;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+        maxAge?: number;
+    };
+}
+/**
+ * 加密 Cookie 配置
+ * @example
+ * ```ts
+ * import type { EncryptedCookieConfig } from '@h-ai/kit'
+ *
+ * function assertKey(config: EncryptedCookieConfig) {
+ *   if (!config.encryptionKey) throw new Error('Encryption key required')
+ * }
+ * ```
+ */
+interface EncryptedCookieConfig {
+    /** Crypto 服务实例 */
+    crypto: CryptoServiceLike;
+    /** 加密密钥 */
+    encryptionKey: string;
+    /** Cookie 选项 */
+    cookieOptions?: {
+        path?: string;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+        maxAge?: number;
+    };
+}
+
+/**
+ * 传输加密配置。
+ *
+ * kit 不再维护本地加解密实现；服务端管理器由 `crypto.transport.createServer()` 创建，
+ * 协议常量与载荷类型统一来自 `@h-ai/crypto`。
+ * @example
+ * ```ts
+ * import type { TransportEncryptionConfig } from '@h-ai/kit'
+ *
+ * function publicPaths(config: TransportEncryptionConfig) { return config.excludePaths ?? [] }
+ * ```
+ */
+interface TransportEncryptionConfig {
+    /** 受管服务端密钥环，仅从服务端 Secret 注入，不放公开 kit 配置。 */
+    serverKeyRing: TransportServerKeyRing;
+    /** 是否启用传输加密（默认 false） */
+    enabled: boolean;
+    /** @h-ai/crypto 服务实例 */
+    crypto: CryptoFunctions;
+    /** 密钥交换端点路径（默认 `/api/_hai/key-exchange`） */
+    keyExchangePath?: string;
+    /** 排除路径（不加密），支持精确匹配和前缀匹配 */
+    excludePaths?: string[];
+    /** 显式客户端公钥存储；生产使用共享 Redis/reldb，内存仅供开发/测试。 */
+    keyStore: TransportKeyStore;
+}
+
+export type { CryptoCsrfConfig as C, EncryptedCookieConfig as E, TransportEncryptionConfig as T, WebhookVerifyConfig as W, CryptoServiceLike as a };

package/dist/{kit-i18n-D9Qqk-1k.d.ts → kit-i18n-DEzmzE5T.d.ts}

@@ -4,9 +4,27 @@
  * 声明式 CRUD 资源定义所需的全部类型。
  * @module kit-crud-types
  */
-/** 支持的字段类型 */
+/**
+ * 支持的字段类型
+ * @example
+ * ```ts
+ * import type { CrudFieldType } from '@h-ai/kit'
+ *
+ * const value: CrudFieldType = 'date-range'
+ * void value
+ * ```
+ */
 type CrudFieldType = 'string' | 'number' | 'boolean' | 'date' | 'date-range' | 'datetime' | 'email' | 'url' | 'tel' | 'password' | 'textarea' | 'select' | 'multi-select' | 'radio' | 'checkbox' | 'custom';
-/** 字段校验规则 */
+/**
+ * 字段校验规则
+ * @example
+ * ```ts
+ * import type { CrudFieldValidation } from '@h-ai/kit'
+ *
+ * const value: CrudFieldValidation = { required: true, max: 120 }
+ * void value
+ * ```
+ */
 interface CrudFieldValidation {
     /** 是否必填 */
     required?: boolean;
@@ -19,16 +37,52 @@ interface CrudFieldValidation {
     /** 自定义错误提示 */
     message?: CrudText;
 }
-/** 选项项（用于 select/radio 等） */
+/**
+ * 选项项（用于 select/radio 等）
+ * @example
+ * ```ts
+ * import type { CrudFieldOption } from '@h-ai/kit'
+ *
+ * const value: CrudFieldOption = { label: 'Published', value: 'published' }
+ * void value
+ * ```
+ */
 interface CrudFieldOption {
     label: string;
     value: string | number | boolean;
 }
-/** 选项来源：静态数组或动态工厂函数 */
+/**
+ * 选项来源：静态数组或动态工厂函数
+ * @example
+ * ```ts
+ * import type { CrudFieldOptions } from '@h-ai/kit'
+ *
+ * const value: CrudFieldOptions = [{ label: 'Published', value: 'published' }]
+ * void value
+ * ```
+ */
 type CrudFieldOptions = CrudFieldOption[] | (() => CrudFieldOption[]);
-/** 可解析为字符串的文本值（支持 i18n） */
+/**
+ * 可解析为字符串的文本值（支持 i18n）
+ * @example
+ * ```ts
+ * import type { CrudText } from '@h-ai/kit'
+ *
+ * const value: CrudText = () => 'Articles'
+ * void value
+ * ```
+ */
 type CrudText = string | (() => string);
-/** 字段定义 */
+/**
+ * 字段定义
+ * @example
+ * ```ts
+ * import type { CrudFieldDef } from '@h-ai/kit'
+ *
+ * const value: CrudFieldDef = { id: 'title', label: 'Title', type: 'string', validation: { required: true } }
+ * void value
+ * ```
+ */
 interface CrudFieldDef {
     /** 字段 ID（对应数据对象的 key） */
     id: string;
@@ -71,24 +125,60 @@ interface CrudFieldDef {
     /** 排列权重（数值越小越靠前） */
     order?: number;
 }
-/** 分页参数 */
+/**
+ * 分页参数
+ * @example
+ * ```ts
+ * import type { CrudPaginationParams } from '@h-ai/kit'
+ *
+ * const value: CrudPaginationParams = { page: 1, pageSize: 20 }
+ * void value
+ * ```
+ */
 interface CrudPaginationParams {
     page: number;
     pageSize: number;
 }
-/** 过滤参数（搜索 + 自定义过滤字段） */
+/**
+ * 过滤参数（搜索 + 自定义过滤字段）
+ * @example
+ * ```ts
+ * import type { CrudFilterParams } from '@h-ai/kit'
+ *
+ * const value: CrudFilterParams = { search: 'example', status: 'published' }
+ * void value
+ * ```
+ */
 interface CrudFilterParams {
     search?: string;
     [key: string]: unknown;
 }
-/** 分页结果 */
+/**
+ * 分页结果
+ * @example
+ * ```ts
+ * import type { CrudPaginatedResult } from '@h-ai/kit'
+ *
+ * const value: CrudPaginatedResult<{ id: string }> = { items: [], total: 0, page: 1, pageSize: 20 }
+ * void value
+ * ```
+ */
 interface CrudPaginatedResult<T> {
     items: T[];
     total: number;
     page: number;
     pageSize: number;
 }
-/** CRUD API 接口定义 */
+/**
+ * CRUD API 接口定义
+ * @example
+ * ```ts
+ * import type { CrudApiDef } from '@h-ai/kit'
+ *
+ * // 应用适配层把持久化查询结果转为此结构，失败应拒绝 Promise。
+ * function listAdapter(list: CrudApiDef<{ id: string }>['list']): CrudApiDef<{ id: string }> { return { list } }
+ * ```
+ */
 interface CrudApiDef<T = Record<string, unknown>> {
     /** 获取分页列表 */
     list: (params: CrudPaginationParams & CrudFilterParams) => Promise<CrudPaginatedResult<T>>;
@@ -101,7 +191,17 @@ interface CrudApiDef<T = Record<string, unknown>> {
     /** 删除记录 */
     remove?: (id: string) => Promise<void>;
 }
-/** CRUD 资源定义 */
+/**
+ * CRUD 资源定义
+ * @example
+ * ```ts
+ * import type { CrudApiDef, CrudResourceDef } from '@h-ai/kit'
+ *
+ * function articles(api: CrudApiDef<{ id: string, title: string }>): CrudResourceDef<{ id: string, title: string }> {
+ *   return { name: 'article', label: 'Articles', fields: [{ id: 'title', label: 'Title', type: 'string' }], api }
+ * }
+ * ```
+ */
 interface CrudResourceDef<T = Record<string, unknown>> {
     /** 资源名称（如 'user', 'role'），用于 URL 路由 */
     name: string;
@@ -120,7 +220,16 @@ interface CrudResourceDef<T = Record<string, unknown>> {
     /** 搜索占位符 */
     searchPlaceholder?: CrudText;
 }
-/** DataTable 列配置（适配 @h-ai/ui DataTable） */
+/**
+ * DataTable 列配置（适配 @h-ai/ui DataTable）
+ * @example
+ * ```ts
+ * import type { CrudTableColumn } from '@h-ai/kit'
+ *
+ * const value: CrudTableColumn = { key: 'title', label: 'Title' }
+ * void value
+ * ```
+ */
 interface CrudTableColumn {
     key: string;
     label: string;
@@ -128,7 +237,15 @@ interface CrudTableColumn {
     align?: 'left' | 'center' | 'right';
     render?: (item: Record<string, unknown>) => string;
 }
-/** CRUD 操作对象（由 defineCrud 返回） */
+/**
+ * CRUD 操作对象（由 defineCrud 返回）
+ * @example
+ * ```ts
+ * import type { CrudOperations } from '@h-ai/kit'
+ *
+ * function columns(resource: CrudOperations<{ id: string }>) { return resource.toTableColumns() }
+ * ```
+ */
 interface CrudOperations<T = Record<string, unknown>> {
     /** 资源元信息 */
     resource: CrudResourceDef<T>;
@@ -176,35 +293,31 @@ declare function resolveOptions(options: CrudFieldOptions | undefined): Array<{
  *
  * @param resource - 资源定义
  * @returns CRUD 操作对象
- *
  * @example
  * ```ts
- * const userCrud = defineCrud({
- *   name: 'user',
- *   label: () => m.users_title(),
- *   fields: [
- *     { id: 'username', label: '用户名', type: 'string', validation: { required: true } },
- *     { id: 'email', label: '邮箱', type: 'email' },
- *   ],
- *   api: { list, get, create, update, remove },
- * })
+ * import { kit } from '@h-ai/kit'
+ *
+ * import type { CrudApiDef } from '@h-ai/kit'
+ *
+ * function articleResource(api: CrudApiDef<{ id: string, title: string }>) {
+ *   return kit.crud.define({ name: 'article', label: 'Articles', fields: [{ id: 'title', label: 'Title', type: 'string' }], api })
+ * }
  * ```
  */
 declare function defineCrud<T = Record<string, unknown>>(resource: CrudResourceDef<T>): CrudOperations<T>;
 
 /**
- * 统一设置所有 hai 模块的默认语言
+ * 设置浏览器应用语言或 Node 启动默认语言；请求中只更新当前 runWithLocale 上下文。
  *
  * 通过 @h-ai/core 的集中式 locale 管理器，一次调用即可同步所有模块。
- * 各模块的 createMessageGetter 会读取全局 locale。
- *
+ * 各模块的 createMessageGetter 优先读取当前 Node 请求上下文；SSR 必须包裹实际 resolve。
+ * @param locale - 支持的应用默认语言；请求中应使用上下文隔离。
  * @example
  * ```ts
  * import { kit } from '@h-ai/kit'
  *
- * // 在 i18n handle 中
- * const locale = event.cookies.get('PARAGLIDE_LOCALE') ?? 'zh-CN'
- * kit.i18n.setLocale(locale)
+ * // 应用启动时设置默认语言；请求内使用 runWithLocale。
+ * kit.i18n.setLocale('en-US')
  * ```
  */
 declare function setAllModulesLocale(locale: string): void;