@h-ai/kit 0.1.0-alpha5

package/dist/index.d.ts

@@ -0,0 +1,963 @@
+import { c as createKitClient, l as login, f as loginWithOtp, g as loginWithLdap, h as loginWithApiKey, r as registerAndLogin, i as logout, s as setBrowserToken, a as clearBrowserToken, b as createTokenStore, d as createHandleFetch } from './index-BotXLTck.js';
+export { C as ClientTransportConfig, K as KitClient, e as KitClientConfig } from './index-BotXLTck.js';
+import { d as defineCrud, s as setAllModulesLocale } from './kit-i18n-CgpNTh9G.js';
+export { C as CrudApiDef, a as CrudFieldDef, b as CrudFieldOption, c as CrudFieldOptions, e as CrudFieldType, f as CrudFieldValidation, g as CrudFilterParams, h as CrudOperations, i as CrudPaginatedResult, j as CrudPaginationParams, k as CrudResourceDef, l as CrudTableColumn, m as CrudText, r as resolveOptions, n as resolveText } from './kit-i18n-CgpNTh9G.js';
+import { S as SessionData, k as RouteGuard, l as SessionLike, h as HandleConfig, C as CorsConfig, M as Middleware } from './kit-types-BHlDNNpd.js';
+export { A as ApiResponse, a as AuthOperations, b as AuthOperationsProvider, F as FormError, c as FormValidationResult, G as GuardConfig, d as GuardResult, H as HaiRequestEvent, e as HandleA2AConfig, f as HandleA2AOperations, g as HandleAuthConfig, i as HookCryptoConfig, m as MemoryRateLimitStore, j as MiddlewareContext, R as RateLimitConfig, n as RateLimitEntry, o as RateLimitStore, T as TransportEncryptionOptions, r as rateLimitMiddleware } from './kit-types-BHlDNNpd.js';
+import { RequestEvent, Cookies, Handle, RequestHandler } from '@sveltejs/kit';
+import { T as TransportCryptoServiceLike } from './kit-crypto-types-C-gEvx04.js';
+export { C as CryptoCsrfConfig, a as CryptoServiceLike, E as EncryptedCookieConfig, b as EncryptedPayload, c as TransportEncryptionConfig, d as TransportEncryptionManager, e as TransportKeyPair, W as WebhookVerifyConfig } from './kit-crypto-types-C-gEvx04.js';
+import * as zod from 'zod';
+import { z } from 'zod';
+import * as zod_v4_core from 'zod/v4/core';
+import { HaiError } from '@h-ai/core';
+export { A2AApiKeyAuthConfig, KitA2AHandlerConfig, ResolvedA2AConfig, createA2AApiKeyAuthenticator, createA2AHandler, createAgentCardHandler, handleA2ARequest, resolveA2AConfig } from './modules/a2a/index.js';
+export { createCsrfManager, createEncryptedCookie, createKeyExchangeHandler, createTransportEncryption, isValidEncryptedPayload, signRequest, transportEncryptionMiddleware, verifyWebhookSignature } from './modules/crypto/index.js';
+import '@h-ai/iam';
+
+/**
+ * @h-ai/kit — 认证守卫
+ *
+ * 验证用户是否已登录
+ * @module kit-auth
+ */
+
+/**
+ * 认证守卫配置
+ */
+interface AuthGuardConfig {
+    /** 未登录时重定向 URL（默认 `'/login'`） */
+    loginUrl?: string;
+    /** 为 `true` 时返回 JSON 401 而非重定向（适用于 API 路由） */
+    apiMode?: boolean;
+}
+/**
+ * 会话守卫配置
+ */
+interface SessionGuardConfig {
+    /** 会话校验函数（通常由应用注入 iam.auth.verifyToken 封装） */
+    validateSession: (token: string) => Promise<SessionData | null>;
+    /** 未登录时重定向 URL（默认 `'/login'`） */
+    loginUrl?: string;
+    /** 为 `true` 时返回 JSON 401 而非重定向（适用于 API 路由） */
+    apiMode?: boolean;
+}
+/**
+ * 创建认证守卫
+ *
+ * 检查会话是否存在；未认证时：
+ * - 页面模式：重定向到 `loginUrl`，并携带 `returnUrl` 参数以便登录后返回。
+ * - API 模式：返回 JSON `{ allowed: false, status: 401 }`。
+ *
+ * @param config - 守卫配置
+ * @returns RouteGuard 实例
+ *
+ * @example
+ * ```ts
+ * // Hook 配置
+ * guards: [
+ *   { guard: kit.guard.auth({ apiMode: true }), paths: ['/api/*'] },
+ *   { guard: kit.guard.auth(), paths: ['/dashboard/*'] },
+ * ]
+ * ```
+ */
+declare function authGuard(config?: AuthGuardConfig): RouteGuard;
+/**
+ * 创建会话守卫（支持 Bearer + 固定 Access Token Cookie 自动恢复）。
+ *
+ * 处理流程：
+ * 1. 若上游已注入 session，直接放行
+ * 2. 否则从 request/cookies 解析 token（Bearer 优先）
+ * 3. 调用 validateSession 恢复并写入 event.locals.session
+ * 4. 失败则按页面/API模式返回重定向或 401
+ */
+declare function sessionGuard(config: SessionGuardConfig): RouteGuard;
+
+/**
+ * @h-ai/kit — 组合守卫
+ *
+ * 提供守卫组合器，支持 AND（allGuards）/ OR（anyGuard）/ NOT（notGuard）/ 条件分支（conditionalGuard）等逻辑组合，将多个 RouteGuard 聚合为一个。
+ * @module kit-compose
+ */
+
+/**
+ * 所有守卫都通过才允许访问（AND 逻辑）
+ *
+ * 短路求值：第一个拒绝的守卫结果会被直接返回。
+ *
+ * @param guards - 需要全部通过的守卫列表
+ * @returns 组合后的 RouteGuard
+ *
+ * @example
+ * ```ts
+ * const adminOnly = kit.guard.all(
+ *   kit.guard.auth(),
+ *   kit.guard.role({ roles: ['admin'] }),
+ * )
+ * ```
+ */
+declare function allGuards(...guards: RouteGuard[]): RouteGuard;
+/**
+ * 任意一个守卫通过就允许访问（OR 逻辑）
+ *
+ * 短路求值：第一个允许的守卫结果会被直接返回。
+ * 全部拒绝时返回最后一个拒绝结果。
+ *
+ * @param guards - 守卫列表
+ * @returns 组合后的 RouteGuard
+ *
+ * @example
+ * ```ts
+ * const canView = kit.guard.any(
+ *   kit.guard.role({ roles: ['admin'] }),
+ *   kit.guard.permission({ permissions: ['article:read'] }),
+ * )
+ * ```
+ */
+declare function anyGuard(...guards: RouteGuard[]): RouteGuard;
+/**
+ * 取反守卫
+ *
+ * 将原守卫的判定逻辑反转：原本放行变为拒绝，原本拒绝变为放行。
+ * 典型场景：「仅未登录用户可访问登录页」。
+ *
+ * @param guard - 需要取反的守卫
+ * @param options - 拒绝时的重定向/消息
+ * @param options.redirect - 拒绝时重定向 URL
+ * @param options.message - 拒绝时的提示消息
+ * @returns 取反后的 RouteGuard
+ *
+ * @example
+ * ```ts
+ * // 仅未登录用户可访问
+ * const guestOnly = kit.guard.not(kit.guard.auth(), { redirect: '/dashboard' })
+ * ```
+ */
+declare function notGuard(guard: RouteGuard, options?: {
+    redirect?: string;
+    message?: string;
+}): RouteGuard;
+/** 条件判断函数类型：返回 `true` 时才执行后续守卫 */
+type ConditionFn = (event: RequestEvent, session: SessionData | undefined) => boolean | Promise<boolean>;
+/**
+ * 条件守卫
+ *
+ * 仅当 `condition` 返回 `true` 时才执行 `guard`；否则直接放行。
+ *
+ * @param condition - 条件判断函数
+ * @param guard - 条件满足时执行的守卫
+ * @returns 包装后的 RouteGuard
+ *
+ * @example
+ * ```ts
+ * // 仅 POST 请求检查 CSRF
+ * kit.guard.conditional(
+ *   (event) => event.request.method === 'POST',
+ *   csrfGuard,
+ * )
+ * ```
+ */
+declare function conditionalGuard(condition: ConditionFn, guard: RouteGuard): RouteGuard;
+
+/**
+ * @h-ai/kit — 权限守卫
+ *
+ * 验证用户是否具有指定权限。
+ * @module kit-permission
+ */
+
+/**
+ * 权限守卫配置
+ */
+interface PermissionGuardConfig {
+    /** 需要的权限列表（默认 OR 逻辑，满足任一即通过） */
+    permissions: string[];
+    /** 为 `true` 时要求用户拥有 **全部** 权限（AND 逻辑） */
+    requireAll?: boolean;
+    /** 无权限时重定向 URL（默认 `'/403'`） */
+    forbiddenUrl?: string;
+    /** 为 `true` 时返回 JSON 403 而非重定向 */
+    apiMode?: boolean;
+}
+/**
+ * 创建权限守卫
+ *
+ * 检查用户 `session.permissions` 是否满足配置中的权限要求。
+ * 支持通配符匹配：`admin:*` 可匹配 `admin:read`、`admin:write` 等。
+ * 未认证时返回 401；权限不匹配时根据 `apiMode` 返回 JSON 403 或重定向。
+ *
+ * @param config - 权限守卫配置
+ * @returns RouteGuard 实例
+ *
+ * @example
+ * ```ts
+ * guards: [
+ *   { guard: kit.guard.permission({ permissions: ['user:read', 'user:write'], requireAll: true }), paths: ['/api/users/*'] },
+ * ]
+ * ```
+ */
+declare function permissionGuard(config: PermissionGuardConfig): RouteGuard;
+/**
+ * 匹配权限
+ *
+ * 支持通配符：
+ * - `admin:*` 匹配 `admin:read`、`admin:write` 等
+ * - `*` 匹配所有权限
+ *
+ * @param required - 需要的权限码
+ * @param userPermissions - 用户已有的权限列表
+ * @returns 是否匹配
+ */
+declare function matchPermission(required: string, userPermissions: string[]): boolean;
+/**
+ * 检查会话是否具有指定权限（布尔判断）
+ *
+ * 适用于条件分支场景（如菜单过滤、按钮显示等）。
+ *
+ * @param session - 当前会话数据，null/undefined 视为无权限
+ * @param permission - 需要的权限码，如 `user:read`
+ * @returns 是否拥有权限
+ *
+ * @example
+ * ```ts
+ * if (kit.guard.check(locals.session, 'user:read')) {
+ *   // 有权限
+ * }
+ * ```
+ */
+declare function hasPermission(session: SessionLike | null | undefined, permission: string): boolean;
+/**
+ * 断言会话具有指定权限，不满足时返回 403 Response
+ *
+ * 适用于 SvelteKit API Handler 内部，不满足权限时直接返回 JSON 错误响应。
+ * 调用者需检查返回值：若有返回值则表示权限不足，应直接 return。
+ *
+ * @param session - 当前会话数据，null/undefined 视为未认证
+ * @param permission - 需要的权限码，如 `user:create`
+ * @returns 权限不足时返回 Response；有权限时返回 undefined
+ *
+ * @example
+ * ```ts
+ * export const POST: RequestHandler = async ({ locals }) => {
+ *   const denied = kit.guard.assertPermission(locals.session, 'user:create')
+ *   if (denied) return denied
+ *   // ... 正常逻辑
+ * }
+ * ```
+ */
+declare function assertPermission(session: SessionLike | null | undefined, permission: string): Response | undefined;
+/**
+ * 要求会话具有指定权限，不满足时 throw Response
+ *
+ * 利用 SvelteKit 控制流机制：throw 的 Response 对象会被框架捕获并直接作为响应返回。
+ * 搭配 `kit.handler()` 使用时，无需手动检查返回值。
+ *
+ * @param session - 当前会话数据，null/undefined 视为未认证
+ * @param permission - 需要的权限码，如 `user:create`
+ * @throws Response - 未认证 401 / 无权限 403
+ *
+ * @example
+ * ```ts
+ * export const GET = kit.handler(async ({ locals }) => {
+ *   kit.guard.require(locals.session, 'user:read')
+ *   // 执行到这里说明权限已通过
+ *   return kit.response.ok(data)
+ * })
+ * ```
+ */
+declare function requirePermission(session: SessionLike | null | undefined, permission: string): void;
+/**
+ * 权限守卫高阶函数包装器
+ *
+ * 将权限检查从业务逻辑中提取到装饰层，handler 内部无需关心权限。
+ * 未认证返回 401、无权限返回 403（均通过 SvelteKit throw 控制流抛出）。
+ *
+ * 适用于 page load、API handler 等所有 SvelteKit server 函数。
+ *
+ * @param permission - 需要的权限码，如 `'user:read'`
+ * @param handler - 原始处理函数
+ * @returns 包装后的处理函数（签名不变）
+ *
+ * @example
+ * ```ts
+ * // +page.server.ts
+ * export const load = kit.guard.withPermission('user:read', async ({ locals }) => {
+ *   const result = await iam.user.listUsers()
+ *   return { users: result.success ? result.data.items : [] }
+ * })
+ *
+ * // +server.ts (API handler)
+ * export const GET = kit.handler(kit.guard.withPermission('user:list', async ({ locals }) => {
+ *   const result = await iam.user.listUsers()
+ *   return kit.response.ok(result.data)
+ * }))
+ * ```
+ */
+declare function withPermission<TEvent extends {
+    locals: Record<string, unknown>;
+}, TReturn>(permission: string, handler: (event: TEvent) => Promise<TReturn>): (event: TEvent) => Promise<TReturn>;
+
+/**
+ * @h-ai/kit — 角色守卫
+ *
+ * 验证用户是否具有指定角色
+ * @module kit-role
+ */
+
+/**
+ * 角色守卫配置
+ */
+interface RoleGuardConfig {
+    /** 需要的角色列表（默认 OR 逻辑，满足任一即通过） */
+    roles: string[];
+    /** 为 `true` 时要求用户拥有 **全部** 角色（AND 逻辑） */
+    requireAll?: boolean;
+    /** 无权限时重定向 URL（默认 `'/403'`） */
+    forbiddenUrl?: string;
+    /** 为 `true` 时返回 JSON 403 而非重定向 */
+    apiMode?: boolean;
+}
+/**
+ * 创建角色守卫
+ *
+ * 检查用户 `session.roles` 是否满足配置中的角色要求。
+ * 未认证时返回 401；角色不匹配时根据 `apiMode` 返回 JSON 403 或重定向。
+ *
+ * @param config - 角色守卫配置
+ * @returns RouteGuard 实例
+ *
+ * @example
+ * ```ts
+ * guards: [
+ *   { guard: kit.guard.role({ roles: ['admin'], apiMode: true }), paths: ['/api/admin/*'] },
+ * ]
+ * ```
+ */
+declare function roleGuard(config: RoleGuardConfig): RouteGuard;
+
+/**
+ * @h-ai/kit — Cookie 加密代理
+ *
+ * 通过 Proxy 拦截 SvelteKit Cookies 对象的 get/set 方法， 对指定名称的 Cookie 自动进行 SM4-CBC 加解密。
+ * @module kit-cookie-proxy
+ */
+
+/**
+ * Cookie 加密代理配置
+ */
+interface CookieProxyConfig {
+    /** 需要加密的 Cookie 名称集合 */
+    names: Set<string>;
+    /** 对称加密服务（SM4） */
+    symmetric: TransportCryptoServiceLike['symmetric'];
+    /** 加密密钥（32 字符十六进制） */
+    encryptionKey: string;
+}
+/**
+ * 创建加密 Cookie 代理
+ *
+ * 返回一个 Proxy 包装的 Cookies 对象：
+ * - `get(name)` —— 若 name 在加密列表中，自动解密后返回明文
+ * - `set(name, value, opts)` —— 若 name 在加密列表中，自动加密后存储
+ * - `delete(name, opts)` —— 透传，无需解密
+ * - 其他方法原样透传
+ *
+ * @param cookies - SvelteKit 原始 Cookies 对象
+ * @param config - 加密配置
+ * @returns 代理后的 Cookies 对象（类型不变）
+ */
+declare function createEncryptedCookieProxy(cookies: Cookies, config: CookieProxyConfig): Cookies;
+
+/**
+ * @h-ai/kit — SvelteKit Handle Hook
+ *
+ * 创建 SvelteKit Handle Hook，集成请求 ID 生成、会话验证、Cookie 加密代理、
+ * 路由守卫、中间件链与可选传输加密；同时提供 `sequence()` 组合多个 Handle。
+ * @module kit-handle
+ */
+
+/**
+ * 创建 hai handle hook
+ *
+ * 整合会话解析、路由守卫、中间件链与统一错误处理的 SvelteKit Handle 工厂。
+ *
+ * 执行顺序：
+ * 1. 生成 `requestId` 并写入 `event.locals`
+ * 2. 根据 `auth` 配置从 Bearer / Cookie 解析会话
+ * 3. 根据 `auth.protectedPaths` 自动执行路由守卫 + 额外自定义守卫
+ * 4. 构建中间件链（内置 logging / rateLimit + 自定义）并执行
+ * 5. 调用 `resolve(event)` 获取业务响应
+ * 6. 附加 `X-Request-Id` 响应头
+ *
+ * @param config - Handle 配置（均有合理默认值，可零配置使用）
+ * @returns SvelteKit Handle 函数
+ *
+ * @example
+ * ```ts
+ * export const handle = kit.createHandle({
+ *   auth: {
+ *     verifyToken: validateSession,
+ *     loginUrl: '/auth/login',
+ *     protectedPaths: ['/admin/*', '/api/*'],
+ *     publicPaths: ['/api/auth/*', '/api/public/*'],
+ *   },
+ *   rateLimit: { maxRequests: 100 },
+ *   crypto: { crypto, transport: true },
+ * })
+ * ```
+ */
+declare function createHandle(config?: HandleConfig): Handle;
+/**
+ * 组合多个 SvelteKit handle 为单一 handle
+ *
+ * 洋葱模型：`sequence(a, b, c)` 执行顺序为 a → b → c → resolve → c → b → a。
+ *
+ * @param handles - 待组合的 handle 函数列表
+ * @returns 组合后的单一 Handle 函数
+ *
+ * @example
+ * ```ts
+ * const haiHandle = kit.createHandle({ ... })
+ * export const handle = kit.sequence(i18nHandle, haiHandle)
+ * ```
+ */
+declare function sequence(...handles: Handle[]): Handle;
+
+/**
+ * @h-ai/kit — 契约 Handler
+ *
+ * 基于 EndpointDef 契约创建类型安全的 API handler：
+ * - 自动从 request body/query 提取参数
+ * - 自动使用契约的 input schema 校验
+ * - handler 返回值类型必须匹配 output schema
+ * - 自动包装为标准 kit.response.ok() 响应
+ * @module kit-contract
+ */
+
+/**
+ * API 端点契约定义
+ *
+ * 客户端和服务端共享的唯一真相源，保证路径、入参、出参编译时一致。
+ */
+interface EndpointDef<TInput = unknown, TOutput = unknown> {
+    /** HTTP 方法 */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** 相对路径（相对于 API 前缀，如 '/auth/login'） */
+    path: string;
+    /** 入参 Zod Schema（GET 请求为 query params，其他为 body） */
+    input: z.ZodType<TInput>;
+    /** 出参 Zod Schema */
+    output: z.ZodType<TOutput>;
+    /** 是否需要认证（默认 true） */
+    requireAuth?: boolean;
+    /** OpenAPI 描述元数据（可选） */
+    meta?: {
+        summary?: string;
+        tags?: string[];
+    };
+}
+/**
+ * 辅助函数：创建端点定义（获得类型推导）
+ *
+ * @param def - 端点定义对象
+ * @returns 同一个对象（类型安全）
+ */
+declare function defineEndpoint<TInput, TOutput>(def: EndpointDef<TInput, TOutput>): EndpointDef<TInput, TOutput>;
+/**
+ * 基于契约创建 API handler
+ *
+ * - 自动从 request body/query 提取参数
+ * - 自动使用契约的 input schema 校验
+ * - handler 返回值类型必须匹配 output schema
+ * - 自动包装为标准 kit.response.ok() 响应
+ *
+ * @param endpoint - 端点契约定义
+ * @param fn - 业务处理函数（接收校验后的 input 和 RequestEvent）
+ * @returns SvelteKit RequestHandler
+ *
+ * @example
+ * ```ts
+ * import { iamEndpoints } from '@h-ai/iam/api'
+ *
+ * export const POST = kit.fromContract(iamEndpoints.login, async (input, event) => {
+ *   const result = await iam.auth.login(input)
+ *   if (!result.success) {
+ *     throw kit.response.error('AUTH_FAILED', result.error.message, 401)
+ *   }
+ *   return result.data
+ * })
+ * ```
+ */
+declare function fromContract<TInput, TOutput>(endpoint: EndpointDef<TInput, TOutput>, fn: (input: TInput, event: RequestEvent) => Promise<TOutput>): RequestHandler;
+
+/**
+ * @h-ai/kit — API Handler 包装器
+ *
+ * 统一封装 SvelteKit API Handler 的错误处理逻辑。
+ * @module kit-handler
+ */
+
+/**
+ * 创建 API Handler 包装器
+ *
+ * 将业务逻辑包裹在统一的异常边界中：
+ * 1. 正常执行 `fn(event)` 返回 Response
+ * 2. 若 `fn` throw 了 `Response`（如 `kit.guard.require` / `kit.validate.body`），直接返回该 Response
+ * 3. 若 `fn` throw 了 SvelteKit 控制流（`redirect()` / `error()`），继续抛出
+ * 4. 其他异常：记录日志 → 返回 `kit.response.internalError()`
+ *
+ * @param fn - 业务处理函数
+ * @returns SvelteKit RequestHandler
+ *
+ * @example
+ * ```ts
+ * export const GET = kit.handler(async ({ locals }) => {
+ *   kit.guard.require(locals.session, 'user:read')
+ *   return kit.response.ok(await getUsers())
+ * })
+ * ```
+ */
+declare function handler(fn: (event: RequestEvent) => Promise<Response> | Response): RequestHandler;
+
+/**
+ * @h-ai/kit — API 响应工具
+ *
+ * 标准化 API 响应工具集，统一 `{ success, data?, error?, requestId? }` 结构。
+ * 提供成功响应（ok / created / noContent）、错误响应
+ * （badRequest / unauthorized / forbidden / notFound / conflict / validationError / internalError）
+ * 以及重定向响应。
+ * @module kit-response
+ */
+
+/**
+ * 创建 200 成功响应
+ *
+ * @param data - 响应数据，序列化为 JSON
+ * @param requestId - 可选请求 ID，用于链路追踪
+ * @returns `{ success: true, data, requestId }` 格式的 JSON Response
+ *
+ * @example
+ * ```ts
+ * return kit.response.ok({ id: '1', name: 'Alice' })
+ * ```
+ */
+declare function ok<T>(data: T, requestId?: string): Response;
+/**
+ * 创建 201 资源创建成功响应
+ *
+ * @param data - 新创建的资源数据
+ * @param requestId - 可选请求 ID
+ * @returns `{ success: true, data }` 格式的 JSON Response（status 201）
+ *
+ * @example
+ * ```ts
+ * return kit.response.created({ id: 'new_1' })
+ * ```
+ */
+declare function created<T>(data: T, requestId?: string): Response;
+/**
+ * 创建 204 无内容响应
+ *
+ * 通常用于 DELETE 成功或无返回值的更新操作。
+ *
+ * @returns 空 body、status 204 的 Response
+ */
+declare function noContent(): Response;
+/**
+ * 创建自定义错误响应
+ *
+ * @param code - 错误码（如 `'CUSTOM_ERROR'`）
+ * @param message - 人可读错误消息
+ * @param status - HTTP 状态码，默认 400
+ * @param requestId - 可选请求 ID
+ * @param details - 可选额外详情
+ * @returns `{ success: false, error: { code, message, details } }` 格式的 JSON Response
+ *
+ * @example
+ * ```ts
+ * return kit.response.error('QUOTA_EXCEEDED', '配额已用尽', 429)
+ * ```
+ */
+declare function error(code: string, message: string, status?: number, requestId?: string, details?: unknown): Response;
+/**
+ * 创建 400 Bad Request 响应
+ *
+ * @param message - 错误消息
+ * @param requestId - 可选请求 ID
+ * @param details - 可选额外详情
+ * @returns error code 为 `'BAD_REQUEST'` 的 JSON Response
+ */
+declare function badRequest(message: string, requestId?: string, details?: unknown): Response;
+/**
+ * 创建 401 Unauthorized 响应
+ *
+ * @param message - 错误消息，默认 `'Authentication required'`
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `'UNAUTHORIZED'` 的 JSON Response
+ */
+declare function unauthorized(message?: string, requestId?: string): Response;
+/**
+ * 创建 403 Forbidden 响应
+ *
+ * @param message - 错误消息，默认 `'Access denied'`
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `'FORBIDDEN'` 的 JSON Response
+ */
+declare function forbidden(message?: string, requestId?: string): Response;
+/**
+ * 创建 404 Not Found 响应
+ *
+ * @param message - 错误消息，默认 `'Resource not found'`
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `'NOT_FOUND'` 的 JSON Response
+ */
+declare function notFound(message?: string, requestId?: string): Response;
+/**
+ * 创建 409 Conflict 响应
+ *
+ * @param message - 冲突描述（如重复创建等）
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `'CONFLICT'` 的 JSON Response
+ */
+declare function conflict(message: string, requestId?: string): Response;
+/**
+ * 创建 422 Unprocessable Entity 响应（验证错误）
+ *
+ * @param errors - 字段级别的验证错误列表
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `'VALIDATION_ERROR'`，details 包含 `errors` 数组
+ *
+ * @example
+ * ```ts
+ * return kit.response.validationError([
+ *   { field: 'email', message: '格式无效' },
+ * ])
+ * ```
+ */
+declare function validationError(errors: Array<{
+    field: string;
+    message: string;
+}>, requestId?: string): Response;
+/**
+ * 创建 500 Internal Server Error 响应
+ *
+ * @param message - 错误消息，默认 `'Internal server error'`
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `'INTERNAL_ERROR'` 的 JSON Response
+ */
+declare function internalError(message?: string, requestId?: string): Response;
+/**
+ * 创建重定向响应
+ *
+ * @param url - 目标 URL
+ * @param status - HTTP 状态码，默认 302；常用 303（POST 后重定向）
+ * @returns 带 `Location` 头的空 body Response
+ *
+ * @example
+ * ```ts
+ * return kit.response.redirect('/dashboard', 303)
+ * ```
+ */
+declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+/**
+ * 将 HaiResult<T> 转换为标准 API Response
+ *
+ * 成功时返回 200 ok(data)，失败时从 error 对象中提取 code、message，
+ * 并根据 httpStatusMap 映射 HTTP 状态码（未命中时默认 400）。
+ *
+ * @param result - core HaiResult 对象（{ success, data } 或 { success: false, error }）
+ * @param httpStatusMap - 模块导出的错误码 → HTTP 状态码映射表（如 IamErrorHttpStatus）
+ * @param requestId - 可选请求 ID，用于链路追踪
+ * @returns 标准化 JSON Response
+ *
+ * @example
+ * ```ts
+ * // 无映射（默认 400）
+ * return kit.response.fromResult(result)
+ *
+ * // 带模块错误码映射
+ * return kit.response.fromResult(result, IamErrorHttpStatus)
+ * ```
+ */
+declare function fromResult<T>(result: {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: {
+        code: number | string;
+        message: string;
+        [key: string]: unknown;
+    };
+}, httpStatusMap?: Record<number | string, number>, requestId?: string): Response;
+declare function fromError(haiError: HaiError, requestId?: string): Response;
+
+/**
+ * @h-ai/kit — 请求数据验证
+ *
+ * 基于 Zod 的请求数据验证工具，支持表单/JSON Body、URL 查询参数与路由参数。
+ * 每种数据源都提供两类 API：
+ * - 安全返回：`FormValidationResult`
+ * - 失败抛出：`OrFail`（抛出 `Response` 以走 SvelteKit 控制流）
+ * @module kit-validation
+ */
+
+/**
+ * 从 Request 解析并验证表单数据，失败时 throw Response
+ *
+ * 与 `validateForm` 功能相同，但校验失败时 throw 400 Response（SvelteKit 控制流），
+ * 搭配 `kit.handler()` 使用可精简 handler 代码。
+ *
+ * @param request - SvelteKit 请求对象
+ * @param schema - Zod Schema
+ * @returns 校验通过的数据（类型安全）
+ * @throws Response - 400 BadRequest（含首条错误消息）
+ *
+ * @example
+ * ```ts
+ * export const POST = kit.handler(async ({ request }) => {
+ *   const data = await kit.validate.body(request, CreateUserSchema)
+ *   // data 类型安全，校验已通过
+ * })
+ * ```
+ */
+declare function validateFormOrFail<T extends z.ZodType>(request: Request, schema: T): Promise<z.infer<T>>;
+/**
+ * 从 URL 查询参数验证，失败时 throw Response
+ *
+ * @param url - 请求 URL 对象
+ * @param schema - Zod Schema
+ * @returns 校验通过的数据
+ * @throws Response - 400 BadRequest
+ *
+ * @example
+ * ```ts
+ * const query = kit.validate.query(event.url, PaginationSchema)
+ * ```
+ */
+declare function validateQueryOrFail<T extends z.ZodType>(url: URL, schema: T): z.infer<T>;
+/**
+ * 验证路径参数，失败时 throw Response
+ *
+ * @param params - SvelteKit 路由参数
+ * @param schema - Zod Schema
+ * @returns 校验通过的数据
+ * @throws Response - 400 BadRequest
+ *
+ * @example
+ * ```ts
+ * const { id } = kit.validate.params(event.params, IdParamSchema)
+ * ```
+ */
+declare function validateParamsOrFail<T extends z.ZodType>(params: Record<string, string>, schema: T): z.infer<T>;
+/**
+ * 路径参数 id 校验 Schema
+ *
+ * 验证 `event.params.id` 为非空字符串。
+ *
+ * @example
+ * ```ts
+ * const { id } = kit.validate.params(event.params, IdParamSchema)
+ * ```
+ */
+declare const IdParamSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * 通用分页查询参数 Schema
+ *
+ * 包含 page（默认 1）、pageSize（默认 20，上限 100）、search（可选）。
+ * 可通过 `.extend()` 扩展业务字段。
+ *
+ * @example
+ * ```ts
+ * // 直接使用
+ * const { page, pageSize, search } = kit.validate.query(url, PaginationQuerySchema)
+ *
+ * // 扩展业务字段
+ * const ListUsersSchema = PaginationQuerySchema.extend({
+ *   enabled: z.enum(['true', 'false']).transform(v => v === 'true').optional(),
+ * })
+ * ```
+ */
+declare const PaginationQuerySchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    search: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+/**
+ * Kit 模块统一出口。
+ *
+ * 作为纯工具模块，kit 不需要 init/close 生命周期，
+ * 所有功能均为无状态工厂函数或工具函数。
+ */
+declare const kit: {
+    /** 创建 SvelteKit Handle Hook（含 auth / logging / rateLimit 内置配置） */
+    createHandle: typeof createHandle;
+    /** 组合多个 Handle */
+    sequence: typeof sequence;
+    /** API Handler 包装器（自动错误边界） */
+    handler: typeof handler;
+    /** 基于 API 契约创建类型安全的路由 handler */
+    fromContract: typeof fromContract;
+    guard: {
+        /** 要求权限，不满足时 throw Response（SvelteKit 控制流） */
+        require: typeof requirePermission;
+        /** 检查会话是否具有指定权限（布尔） */
+        check: typeof hasPermission;
+    };
+    response: {
+        /** 200 成功 */
+        ok: typeof ok;
+        /** 201 创建成功 */
+        created: typeof created;
+        /** 204 无内容 */
+        noContent: typeof noContent;
+        /** 自定义错误响应 */
+        error: typeof error;
+        /** 400 BadRequest */
+        badRequest: typeof badRequest;
+        /** 401 Unauthorized */
+        unauthorized: typeof unauthorized;
+        /** 403 Forbidden */
+        forbidden: typeof forbidden;
+        /** 404 NotFound */
+        notFound: typeof notFound;
+        /** 409 Conflict */
+        conflict: typeof conflict;
+        /** 422 验证错误 */
+        validationError: typeof validationError;
+        /** 500 InternalError */
+        internalError: typeof internalError;
+        /** 重定向 */
+        redirect: typeof redirect;
+        /** 将 HaiResult<T> 转为标准 API Response（支持 httpStatusMap） */
+        fromResult: typeof fromResult;
+        /** 将模块错误码映射为标准 HTTP Response */
+        fromError: typeof fromError;
+    };
+    validate: {
+        /** 验证请求体（JSON/表单），失败 throw Response */
+        body: typeof validateFormOrFail;
+        /** 验证查询参数，失败 throw Response */
+        query: typeof validateQueryOrFail;
+        /** 验证路径参数，失败 throw Response */
+        params: typeof validateParamsOrFail;
+        /** 路径参数 id Schema（{id: string}） */
+        IdParamSchema: zod.ZodObject<{
+            id: zod.ZodString;
+        }, zod_v4_core.$strip>;
+        /** 通用分页查询 Schema（page / pageSize / search） */
+        PaginationQuerySchema: zod.ZodObject<{
+            page: zod.ZodDefault<zod.ZodCoercedNumber<unknown>>;
+            pageSize: zod.ZodDefault<zod.ZodCoercedNumber<unknown>>;
+            search: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strip>;
+    };
+    client: {
+        /** 创建统一客户端（CSRF + 传输加密透明合并） */
+        create: typeof createKitClient;
+    };
+    auth: {
+        /** 服务端登录（密码）：内部调用 iam.auth.login + 自动写入 Token Cookie */
+        login: typeof login;
+        /** 服务端登录（OTP 验证码）：内部调用 iam.auth.loginWithOtp + 自动写入 Token Cookie */
+        loginWithOtp: typeof loginWithOtp;
+        /** 服务端登录（LDAP）：内部调用 iam.auth.loginWithLdap + 自动写入 Token Cookie */
+        loginWithLdap: typeof loginWithLdap;
+        /** 服务端登录（API Key）：内部调用 iam.auth.loginWithApiKey + 自动写入 Token Cookie */
+        loginWithApiKey: typeof loginWithApiKey;
+        /** 服务端注册并登录：内部调用 iam.auth.registerAndLogin + 自动写入 Token Cookie */
+        registerAndLogin: typeof registerAndLogin;
+        /** 服务端登出：内部调用 iam.auth.logout + 清除 Token Cookie */
+        logout: typeof logout;
+        /** 写入浏览器端 Access Token（客户端 login/register 用） */
+        setBrowserToken: typeof setBrowserToken;
+        /** 清除浏览器端 Access Token（客户端 logout 用） */
+        clearBrowserToken: typeof clearBrowserToken;
+        /** 创建浏览器端 Token 存储器（自定义 key 时使用） */
+        createTokenStore: typeof createTokenStore;
+        /** 创建浏览器端同源请求自动附加 Authorization 的 HandleFetch */
+        createHandleFetch: typeof createHandleFetch;
+    };
+    crud: {
+        /** 定义 CRUD 资源（声明式配置 → 操作对象） */
+        define: typeof defineCrud;
+    };
+    i18n: {
+        /** 统一设置所有 hai 模块的默认语言 */
+        setLocale: typeof setAllModulesLocale;
+    };
+};
+
+/**
+ * @h-ai/kit — CORS 中间件
+ *
+ * 配置跨域资源共享（CORS）策略，自动处理 OPTIONS 预检请求与响应头注入。
+ * 支持精确 origin、数组白名单、通配符模式与函数匹配四种模式。
+ * 自动预置 Capacitor WebView origin（Android/iOS）。
+ * @module kit-cors
+ */
+
+/**
+ * 创建 CORS 中间件
+ *
+ * 处理跨域资源共享：
+ * - OPTIONS 预检请求返回 204 + CORS 头
+ * - 其他请求在业务响应上附加 CORS 头
+ * - 默认预置 Capacitor WebView origin
+ *
+ * @param config - CORS 配置（省略则允许所有 origin）
+ * @returns Middleware 实例
+ *
+ * @example
+ * ```ts
+ * middleware: [
+ *   kit.middleware.cors({ origin: ['https://example.com'], credentials: true }),
+ * ]
+ * ```
+ */
+declare function corsMiddleware(config?: CorsConfig): Middleware;
+
+/**
+ * @h-ai/kit — 日志中间件
+ *
+ * HTTP 请求日志中间件，记录请求/响应摘要（方法、路径、状态码、耗时），
+ * 并自动脱敏敏感字段（password / token / secret 等）。
+ * @module kit-logging
+ */
+
+/**
+ * 日志中间件配置
+ */
+interface LoggingMiddlewareConfig {
+    /** 为 `true` 时记录非 GET 请求体（自动脱敏） */
+    logBody?: boolean;
+    /** 为 `true` 时记录响应头 */
+    logResponse?: boolean;
+    /** 指定需要脱敏的字段名（默认 `['password', 'token', 'secret']`） */
+    redactFields?: string[];
+}
+/**
+ * 创建日志中间件
+ *
+ * 以 `core.logger.trace` 级别记录请求进出信息，包含：
+ * - 请求：method / path / query / userAgent / ip
+ * - 响应：status / duration
+ *
+ * 敏感字段会被自动替换为 `[REDACTED]`。
+ *
+ * @param config - 日志配置
+ * @returns Middleware 实例
+ *
+ * @example
+ * ```ts
+ * middleware: [
+ *   kit.middleware.logging({ logBody: true, redactFields: ['password', 'creditCard'] }),
+ * ]
+ * ```
+ */
+declare function loggingMiddleware(config?: LoggingMiddlewareConfig): Middleware;
+
+export { type AuthGuardConfig, type CookieProxyConfig, CorsConfig, type EndpointDef, HandleConfig, IdParamSchema, type LoggingMiddlewareConfig, Middleware, PaginationQuerySchema, type PermissionGuardConfig, type RoleGuardConfig, RouteGuard, SessionData, type SessionGuardConfig, SessionLike, TransportCryptoServiceLike, allGuards, anyGuard, assertPermission, authGuard, conditionalGuard, corsMiddleware, createEncryptedCookieProxy, createHandle, createKitClient, defineCrud, defineEndpoint, hasPermission, kit, loggingMiddleware, matchPermission, notGuard, permissionGuard, requirePermission, roleGuard, sequence, sessionGuard, withPermission };