@h-ai/kit 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/kit-types-Cr1cnB3M.d.ts

@@ -0,0 +1,2051 @@
+import { HaiResult, HaiError, TrustedProxies, RequestAccessConfigInput, core } from '@h-ai/core';
+import { CryptoFunctions, TransportServerKeyRing, TransportKeyStore } from '@h-ai/crypto';
+import { IamFunctions, AuthnOperations, PasswordCredentials, AuthRequestContext, AuthResult, OtpCredentials, LdapCredentials, ApiKeyCredentials, RegisterOptions } from '@h-ai/iam';
+import * as _sveltejs_kit from '@sveltejs/kit';
+import { RequestEvent, RequestHandler } from '@sveltejs/kit';
+import { IamCreateCaptchaInputSchema, IamPublicConfig, IamLoginInput, IamRegisterInput } from '@h-ai/api-contract';
+import { Handle } from '@sveltejs/kit/hooks';
+import { FeedbackFunctions, FeedbackContext } from '@h-ai/feedback';
+import { z } from 'zod';
+
+/**
+ * @h-ai/kit — Bearer 认证工具
+ *
+ * 提供服务端认证 Cookie 管理（login / logout）与浏览器端 Token 存储工具。
+ * @module kit-auth
+ */
+
+/**
+ * 浏览器 Token 存储器；使用页面内存或平台安全存储，禁止写入 Web Storage。
+ * @example 模块内部上下文
+ * ```ts
+ * const store: BrowserTokenStore = getDefaultBrowserTokenStore()
+ * store.clear() // 当前页面内存状态；不持有服务端会话真值。
+ * ```
+ */
+interface BrowserTokenStore {
+    get: () => string | null;
+    set: (token: string) => void;
+    clear: () => void;
+}
+
+/**
+ * @h-ai/kit — 统一客户端
+ *
+ * 将 CSRF Token 附加与可选传输加密封装为统一 `apiFetch`。
+ * 应用层只需调用一次 `createKitClient()`，后续 API 调用即可复用同一套安全能力。
+ * @module kit-client
+ */
+
+/**
+ * 传输加密客户端配置
+ * @example
+ * ```ts
+ * import type { ClientTransportConfig } from '@h-ai/kit'
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function configAfterInit(): ClientTransportConfig { return { crypto, excludePaths: ['/api/health'] } }
+ * ```
+ */
+interface ClientTransportConfig {
+    /** 宿主构建挂载目录，默认空字符串；SvelteKit 使用 paths.relative=false 时的 resolve('/').replace(/\/$/, '')。 */
+    basePath?: string;
+    /** 可选本地明文上限；缺省跟随服务端握手。 */
+    maxPlaintextBytes?: number;
+    /** @h-ai/crypto 服务实例 */
+    crypto: CryptoFunctions;
+    /** 密钥交换端点 URL（默认 `'/api/_hai/key-exchange'`） */
+    keyExchangeUrl?: string;
+    /** 排除路径（命中后强制走明文），需与服务端 transport.excludePaths 保持一致 */
+    excludePaths?: readonly string[];
+}
+/**
+ * Kit 客户端配置
+ * @example
+ * ```ts
+ * import type { KitClientConfig } from '@h-ai/kit'
+ *
+ * const value: KitClientConfig = { auth: true }
+ * void value
+ * ```
+ */
+interface KitClientConfig {
+    /** 标准鉴别明确失效时原地登录原用户；成功才对被拒绝的请求重试一次。 */
+    recoverSession?: () => Promise<boolean>;
+    /** 会话终端分组，默认web；服务端按终端与全局配额共同限制。 */
+    terminalType?: 'web' | 'app' | 'desktop' | 'api';
+    /**
+     * 传输加密配置。
+     * - 不提供 / undefined：不启用传输加密，仅 CSRF
+     * - 提供对象：启用传输加密
+     */
+    transport?: ClientTransportConfig;
+    /** CSRF Cookie 名称（默认 `'hai_csrf'`） */
+    csrfCookieName?: string;
+    /** CSRF Header 名称（默认 `'X-CSRF-Token'`） */
+    csrfHeaderName?: string;
+    /**
+     * 认证配置：自动从浏览器存储读取 Access Token 并注入请求头。
+     * - `true`：使用默认页面内存存储（由 `kit.auth.setBrowserToken()` 写入，不读写 localStorage）
+     * - `BrowserTokenStore`：使用自定义存储
+     * - 不提供 / `false`：不自动注入
+     */
+    auth?: boolean | BrowserTokenStore;
+}
+/**
+ * Kit 客户端实例
+ * @example
+ * ```ts
+ * import type { KitClient } from '@h-ai/kit'
+ *
+ * async function read(client: KitClient) {
+ *   const response = await client.apiFetch('/api/health')
+ *   if (!response.ok) throw new Error('Request failed')
+ *   return response.json()
+ * }
+ * ```
+ */
+interface KitClient {
+    /** 统一 API fetch（写请求自动附加 CSRF，启用 transport 时自动加解密） */
+    apiFetch: (input: RequestInfo | URL, init?: RequestInit, options?: {
+        recoverSession?: boolean;
+        reauthorize?: () => Promise<string | null | undefined>;
+    }) => Promise<Response>;
+    /** 传输加密是否就绪（未启用传输加密时始终为 true） */
+    readonly ready: boolean;
+    /**
+     * 手动触发密钥交换（transport 启用时）。
+     *
+     * 注意：本方法是 Client 形态的合规例外，密钥协商失败时 `throw`（与 `@h-ai/api-client` 一致），
+     * 调用方需自行 `try/catch`，不返回 `HaiResult`。
+     */
+    init: () => Promise<void>;
+    /** 销毁密钥状态 */
+    destroy: () => void;
+}
+/**
+ * 在浏览器启动时安装同源 transport fetch 包装。
+ *
+ * 该包装作用于同源 `/api/*` 与 SvelteKit `__data.json` 请求，页面文档、
+ * 静态资源以及 multipart/form-data 等上传请求保持原样。应用只需安装一次，
+ * 后续 `fetch` / SvelteKit 内部 data fetch / `kit.client.create()` 明文发送路径
+ * 都会共用这层传输加密能力。
+ * @param transportConfig - 已初始化 crypto、同源密钥交换路径及排除路径；省略时不安装包装。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * // 不传配置时不安装全局包装；启用时应传已初始化 crypto 与同源端点。
+ * kit.client.installBrowserTransportFetch()
+ * ```
+ */
+declare function installBrowserTransportFetch(transportConfig?: ClientTransportConfig): void;
+/**
+ * 用 `config/_kit.yml` 解析后的 {@link KitPublicConfig} 公共投影 一次性安装浏览器端传输加密。
+ *
+ * 行为：
+ * - `config.transport === false` 时直接返回（不启用传输加密）；
+ * - 否则启动 {@link installBrowserTransportFetch}，并预热 {@link CryptoFunctions} 模块。
+ *
+ * 应用层（SvelteKit `+layout.svelte` 或浏览器入口）只需调用此函数一次，
+ * 之后宿主 basePath 下的同源 `/api/*` 与 `__data.json` 请求都会自动走传输加密。
+ *
+ * @param config 已解析的 kit 公共传输配置
+ * @param deps  外部依赖
+ * @param deps.crypto `@h-ai/crypto` 模块实例
+ * @param deps.basePath 宿主构建挂载目录，默认空字符串；SvelteKit 使用 paths.relative=false 时的 resolve('/').replace(/\/$/, '')。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function installAfterCryptoInit() {
+ *   kit.client.installBrowserTransport({ transport: { keyExchangePath: '/api/_hai/key-exchange', excludePaths: ['/api/health'] } }, { crypto })
+ * }
+ * ```
+ */
+declare function installBrowserTransport(config: KitPublicConfig, deps: {
+    crypto: CryptoFunctions;
+    basePath?: string;
+}): void;
+/**
+ * 创建 Kit 客户端
+ *
+ * 返回统一的 `apiFetch`，内部自动完成：
+ * 1. CSRF Token 附加（写方法自动读取 Cookie + 设置 Header）
+ * 2. 密钥交换（首次写请求时 lazy init，transport 启用时）
+ * 3. 请求体加密（transport 启用时）
+ * 4. 响应体解密（transport 启用时）
+ *
+ * @param config - 客户端配置
+ * @returns KitClient 实例
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const client = kit.client.create({ auth: true })
+ * try {
+ *   await client.init() // Client API 使用 Promise 拒绝；不是 HaiResult。
+ *   const response = await client.apiFetch('/api/health')
+ *   if (!response.ok) throw new Error('Request failed')
+ * } finally {
+ *   client.destroy()
+ * }
+ * ```
+ */
+declare function createKitClient(config?: KitClientConfig): KitClient;
+
+/** 与标准 Kit 认证端点配套的表单动作；复用已有 CSRF/transport fetch。 */
+
+/**
+ * 创建标准 Cookie 认证表单动作；复用可选 apiFetch 以保留 CSRF 和传输配置。
+ * @param options - 可复用的 apiFetch 和标准认证端点 basePath。
+ * @param options.apiFetch - 已装配 CSRF/transport 的 fetch；省略时使用默认 Kit 客户端。
+ * @param options.basePath - 同源认证端点前缀，默认 /api/auth。
+ * @returns 标准表单动作；业务和已认证的时间错误返回 HaiResult，网络/格式错误会拒绝 Promise。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const actions = kit.client.createAuthActions({ basePath: '/api/auth' })
+ * void actions
+ * ```
+ */
+declare function createKitAuthActions(options?: {
+    apiFetch?: KitClient['apiFetch'];
+    basePath?: string;
+}): {
+    bindPageExit(options?: {
+        enabled?: boolean;
+    }): () => void;
+    createCaptcha(input: z.input<typeof IamCreateCaptchaInputSchema>): Promise<HaiResult<{
+        id: string;
+        challenge: {
+            parameters: {
+                algorithm: "PBKDF2/SHA-256";
+                nonce: string;
+                salt: string;
+                cost: number;
+                keyLength: number;
+                keyPrefix: string;
+                keySignature?: string | undefined;
+                data?: Record<string, string | number | boolean | null> | undefined;
+            };
+            signature?: string | undefined;
+        };
+    }>>;
+    publicConfig(): Promise<HaiResult<IamPublicConfig | null>>;
+    login(input: IamLoginInput & {
+        method?: "password" | "ldap" | "email" | "sms";
+        code?: string;
+    }): Promise<HaiResult<unknown>>;
+    register: (input: IamRegisterInput) => Promise<HaiResult<unknown>>;
+    sendOtp: (identifier: string, options?: {
+        captcha?: string;
+    }) => Promise<HaiResult<unknown>>;
+    requestPasswordReset: (identifier: string, options?: {
+        captcha?: string;
+    }) => Promise<HaiResult<unknown>>;
+    confirmPasswordReset: (token: string, newPassword: string) => Promise<HaiResult<unknown>>;
+    renewPassword: (input: {
+        identifier: string;
+        password: string;
+        newPassword: string;
+        captcha?: string;
+    }) => Promise<HaiResult<unknown>>;
+    reauthenticate(password: string, operation: string): Promise<HaiResult<{
+        ticket: string;
+        expiresAt: number;
+    }>>;
+};
+
+/**
+ * @h-ai/kit — CRUD 类型定义
+ *
+ * 声明式 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;
+    /** 最小值（number）或 最小长度（string） */
+    min?: number;
+    /** 最大值（number）或 最大长度（string） */
+    max?: number;
+    /** 正则表达式 */
+    pattern?: string;
+    /** 自定义错误提示 */
+    message?: CrudText;
+}
+/**
+ * 选项项（用于 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）
+ * @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;
+    /** 显示名称（支持 i18n 函数） */
+    label: CrudText;
+    /** 字段类型 */
+    type: CrudFieldType;
+    /** 是否在列表中显示（默认 true） */
+    inList?: boolean;
+    /** 是否是过滤项（默认 false） */
+    filterable?: boolean;
+    /** 是否只读（编辑时不可修改，默认 false） */
+    readonly?: boolean;
+    /** 是否在新建表单中显示（默认 true） */
+    inCreate?: boolean;
+    /** 是否在编辑表单中显示（默认 true） */
+    inEdit?: boolean;
+    /** 是否在详情中显示（默认 true） */
+    inDetail?: boolean;
+    /** 选项列表（select/radio/checkbox/multi-select） */
+    options?: CrudFieldOptions;
+    /** 校验规则 */
+    validation?: CrudFieldValidation;
+    /** 双列表单中的占用列数；auto 按控件类型判断，默认 auto。 */
+    colSpan?: 'auto' | 1 | 2;
+    /** 列宽（列表模式） */
+    width?: string;
+    /** 列对齐方式 */
+    align?: 'left' | 'center' | 'right';
+    /** 自定义列表渲染 */
+    render?: (value: unknown, item: Record<string, unknown>) => string;
+    /** 占位符 */
+    placeholder?: CrudText;
+    /** 日期范围起始值的查询参数名；仅 date-range 字段使用，默认 `${id}Start` */
+    startKey?: string;
+    /** 日期范围结束值的查询参数名；仅 date-range 字段使用，默认 `${id}End` */
+    endKey?: string;
+    /** 默认值（新建时） */
+    defaultValue?: unknown;
+    /** 排列权重（数值越小越靠前） */
+    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 接口定义
+ * @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>>;
+    /** 获取单条记录 */
+    get?: (id: string) => Promise<T | null>;
+    /** 新建记录 */
+    create?: (data: Partial<T>) => Promise<T>;
+    /** 更新记录（patch） */
+    update?: (id: string, data: Partial<T>) => Promise<T>;
+    /** 删除记录 */
+    remove?: (id: string) => Promise<void>;
+}
+/**
+ * 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;
+    /** 显示名称（面包屑、标题用，支持 i18n） */
+    label: CrudText;
+    /** 主键字段名（默认 'id'） */
+    keyField?: string;
+    /** 字段列表 */
+    fields: CrudFieldDef[];
+    /** API 接口 */
+    api: CrudApiDef<T>;
+    /** 默认分页大小（默认 20） */
+    defaultPageSize?: number;
+    /** 是否支持搜索（默认 true） */
+    searchable?: boolean;
+    /** 搜索占位符 */
+    searchPlaceholder?: CrudText;
+}
+/**
+ * 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;
+    width?: string;
+    align?: 'left' | 'center' | 'right';
+    render?: (item: Record<string, unknown>) => string;
+}
+/**
+ * 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>;
+    /** 获取列表列字段（inList=true） */
+    getListFields: () => CrudFieldDef[];
+    /** 获取过滤字段（filterable=true） */
+    getFilterFields: () => CrudFieldDef[];
+    /** 获取新建表单字段（inCreate=true） */
+    getCreateFields: () => CrudFieldDef[];
+    /** 获取编辑表单字段（inEdit=true） */
+    getEditFields: () => CrudFieldDef[];
+    /** 获取详情字段（inDetail=true） */
+    getDetailFields: () => CrudFieldDef[];
+    /** 构建 DataTable 列配置 */
+    toTableColumns: () => CrudTableColumn[];
+    /** 构建新建时的默认值 */
+    getDefaultValues: () => Record<string, unknown>;
+    /** API 操作代理 */
+    api: CrudApiDef<T>;
+}
+
+/**
+ * @h-ai/kit — CRUD 操作定义
+ *
+ * 声明式 CRUD 资源定义工厂函数。
+ * @module kit-crud
+ */
+
+/**
+ * 解析 CrudText 为字符串
+ */
+declare function resolveText(text: CrudText): string;
+/**
+ * 解析选项列表
+ */
+declare function resolveOptions(options: CrudFieldOptions | undefined): Array<{
+    label: string;
+    value: string | number | boolean;
+}>;
+/**
+ * 定义 CRUD 资源
+ *
+ * 返回 CrudOperations 对象，包含字段过滤、列构建和 API 代理等能力。
+ * 与 @h-ai/ui 的 CrudPage 组件配合使用。
+ *
+ * @param resource - 资源定义
+ * @returns CRUD 操作对象
+ * @example
+ * ```ts
+ * 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>;
+
+/**
+ * @h-ai/kit — 权限守卫
+ *
+ * 验证用户是否具有指定权限。
+ * @module kit-permission
+ */
+
+/**
+ * 权限守卫配置
+ * @example
+ * ```ts
+ * import type { PermissionGuardConfig } from '@h-ai/kit'
+ *
+ * const value: PermissionGuardConfig = { permissions: ['article:read'] }
+ * void value
+ * ```
+ */
+interface PermissionGuardConfig {
+    /** 需要的权限列表（默认 OR 逻辑，满足任一即通过） */
+    permissions: string[];
+    /** 为 `true` 时要求用户拥有 **全部** 权限（AND 逻辑） */
+    requireAll?: boolean;
+    /** 无权限时重定向 URL（默认 `'/403'`） */
+    forbiddenUrl?: string;
+    /** 为 `true` 时返回 JSON 403 而非重定向 */
+    apiMode?: boolean;
+}
+/**
+ * 匹配权限
+ *
+ * 支持通配符：
+ * - `admin:*` 匹配 `admin:read`、`admin:write` 等
+ * - `*` 匹配所有权限
+ *
+ * @param required - 需要的权限码
+ * @param userPermissions - 用户已有的权限列表
+ * @returns 是否匹配
+ * @example
+ * ```ts
+ * import { matchPermission } from '@h-ai/kit'
+ *
+ * const allowed = matchPermission('article:read', ['article:*'])
+ * void allowed
+ * ```
+ */
+declare function matchPermission(required: string, userPermissions: string[]): boolean;
+/**
+ * 检查会话是否具有指定权限（布尔判断）
+ *
+ * 适用于条件分支场景（如菜单过滤、按钮显示等）。
+ *
+ * @param session - 当前会话数据，null/undefined 视为无权限
+ * @param permission - 需要的权限码，如 `user:read`
+ * @returns 是否拥有权限
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const allowed = kit.guard.check({ userId: 'user_1', roles: ['editor'], permissions: ['article:read'] }, 'article:read')
+ * void allowed
+ * ```
+ */
+declare function hasPermission(session: SessionLike | null | undefined, permission: string): boolean;
+/**
+ * 要求会话具有指定权限，不满足时 throw Response
+ *
+ * throw 的 Response 对象由 kit.handler 捕获并直接作为 API 响应返回。
+ * 搭配 `kit.handler()` 使用时，无需手动检查返回值。
+ *
+ * @param session - 当前会话数据，null/undefined 视为未认证
+ * @param permission - 需要的权限码，如 `user:create`
+ * @throws Response - 未认证 401 / 无权限 403
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * kit.guard.require({ userId: 'user_1', roles: ['editor'], permissions: ['article:read'] }, 'article:read') // 拒绝时抛出 Response，由 kit.handler 传递。
+ * ```
+ */
+declare function requirePermission(session: SessionLike | null | undefined, permission: string): void;
+
+/** 可选敏感操作再鉴别；由操作入口在现有权限/资源检查之后调用。 */
+
+/**
+ * 要求选定操作携带短期单次再鉴别票据；失败抛出 Response，由 kit.handler 返回。
+ * 不替代已有认证、权限与资源范围守卫；操作 ID 必须由服务端指定。
+ * @param iam - 已初始化的 IAM 服务。
+ * @param event - 当前请求与 Cookie，不能跨请求保存。
+ * @param operation - 当前服务端操作 ID。
+ * @returns 策略关闭、未选操作或证明校验成功时无返回值。
+ * @example
+ * ```ts
+ * import { iam } from '@h-ai/iam'
+ * import type { SessionLike } from '@h-ai/kit'
+ * import type { RequestEvent } from '@sveltejs/kit'
+ * import { kit } from '@h-ai/kit'
+ * // session 由应用在当前请求完成鉴别后传入，不在跨请求闭包中保存。
+ * async function remove(event: Pick<RequestEvent, 'request' | 'cookies'>, session: SessionLike) {
+ *   kit.guard.require(session, 'user:delete')
+ *   await kit.guard.requireSensitive(iam, event, 'iam.users.delete')
+ *   return kit.response.ok({ allowed: true })
+ * }
+ * ```
+ */
+declare function requireSensitiveOperation(iam: IamFunctions, event: Pick<RequestEvent, 'request' | 'cookies'>, operation: string): Promise<void>;
+
+/**
+ * @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
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.createHandle({ auth: { verifyToken: async () => null, protectedPaths: ['/admin/**'] } })
+ * void handle
+ * ```
+ */
+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
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.sequence(kit.createHandle({ logging: true }), kit.createHandle())
+ * void handle
+ * ```
+ */
+declare function sequence(...handles: Handle[]): Handle;
+
+/**
+ * 应用路由直接导出对应 handler；认证 ops 仍由 createHandle 注入。
+ * @param iam - 已由应用初始化的 IAM 服务对象。
+ * @returns 标准认证端点的 RequestHandler 集合。
+ * @example 模块内部上下文
+ * ```ts
+ * function build(iam: IamFunctions) {
+ *   return createAuthApi(iam) // 调用方负责初始化 IAM；工厂只装配 handler。
+ * }
+ * ```
+ */
+declare function createAuthApi(iam: IamFunctions): {
+    closeSession: _sveltejs_kit.RequestHandler;
+    createCaptcha: _sveltejs_kit.RequestHandler;
+    reauthenticate: _sveltejs_kit.RequestHandler;
+    publicConfig: _sveltejs_kit.RequestHandler;
+    renewPassword: _sveltejs_kit.RequestHandler;
+    login: _sveltejs_kit.RequestHandler;
+    loginWithLdap: _sveltejs_kit.RequestHandler;
+    loginWithOtp: _sveltejs_kit.RequestHandler;
+    register: _sveltejs_kit.RequestHandler;
+    sendOtp: _sveltejs_kit.RequestHandler;
+    requestPasswordReset: _sveltejs_kit.RequestHandler;
+    confirmPasswordReset: _sveltejs_kit.RequestHandler;
+};
+
+/** 可直接挂到 SvelteKit catch-all 路由的反馈适配，无 serv 或 Svelte UI 依赖。 */
+
+/**
+ * 反馈服务及可信范围解析。resolveContext 必须使用已验证 session/宿主策略。
+ * @example
+ * ```ts
+ * import type { FeedbackHandlerOptions } from '@h-ai/kit'
+ * import { feedback } from '@h-ai/feedback'
+ * const options: FeedbackHandlerOptions = { feedback, resolveContext: () => null }
+ * // 应用实现真实 session 映射；null 拒绝访问，不能从 JSON 取得身份。
+ * ```
+ */
+interface FeedbackHandlerOptions {
+    readonly feedback: FeedbackFunctions;
+    readonly resolveContext: (event: RequestEvent) => FeedbackContext | null | Promise<FeedbackContext | null>;
+    readonly basePath?: string;
+}
+/**
+ * 装配反馈 REST 路由；默认路径 /api/feedback，由宿主 handle 保持 CSRF、认证和传输加密。
+ * @param options - 已初始化服务与可信范围映射。
+ * @returns 可赋值给 catch-all 路由 GET/POST/PATCH 的同一 handler。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ * import { feedback } from '@h-ai/feedback'
+ * const handler = kit.createFeedbackHandler({ feedback, resolveContext: () => null })
+ * // 路由 export const GET = handler；真实应用从受信 session 返回范围，null 默认拒绝。
+ * ```
+ */
+declare function createFeedbackHandler(options: FeedbackHandlerOptions): 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
+ * import { kit } from '@h-ai/kit'
+ *
+ * const GET = kit.handler(() => kit.response.ok({ healthy: true }))
+ * void GET
+ * ```
+ */
+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
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.ok({ id: 'article_1' })
+ * void response.status
+ * ```
+ */
+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
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.created({ id: 'article_1' })
+ * void response.status
+ * ```
+ */
+declare function created<T>(data: T, requestId?: string): Response;
+/**
+ * 创建 204 无内容响应
+ *
+ * 通常用于 DELETE 成功或无返回值的更新操作。
+ *
+ * @returns 空 body、status 204 的 Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.noContent()
+ * void response.status
+ * ```
+ */
+declare function noContent(): Response;
+/**
+ * 创建自定义错误响应
+ *
+ * @param code - 错误码（如 `'CUSTOM_ERROR'`）
+ * @param message - 人可读错误消息
+ * @param status - HTTP 状态码，默认 400
+ * @param requestId - 可选请求 ID
+ * @param details - 显式公开的业务详情；不要传原始异常、SQL、输入值或内部上下文
+ * @returns `{ success: false, error: { code, message, details } }` 格式的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.error('ARTICLE_MISSING', 'Article missing', 404)
+ * void response.status
+ * ```
+ */
+declare function error(code: HaiError['code'], message: string, status?: number, requestId?: string, details?: unknown): Response;
+/**
+ * 创建 400 Bad Request 响应
+ *
+ * @param message - 错误消息
+ * @param requestId - 可选请求 ID
+ * @param details - 可选额外详情
+ * @returns error code 为 `HaiCommonError.INVALID_REQUEST.code` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.badRequest('Invalid article')
+ * void response.status
+ * ```
+ */
+declare function badRequest(message: string, requestId?: string, details?: unknown): Response;
+/**
+ * 创建 401 Unauthorized 响应
+ *
+ * @param message - 错误消息，默认 `'Authentication required'`
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `HaiCommonError.UNAUTHORIZED.code` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.unauthorized()
+ * void response.status
+ * ```
+ */
+declare function unauthorized(message?: string, requestId?: string): Response;
+/**
+ * 创建 403 Forbidden 响应
+ *
+ * @param message - 错误消息，默认 `'Access denied'`
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `HaiCommonError.FORBIDDEN.code` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.forbidden()
+ * void response.status
+ * ```
+ */
+declare function forbidden(message?: string, requestId?: string): Response;
+/**
+ * 创建 404 Not Found 响应
+ *
+ * @param message - 错误消息，默认 `'Resource not found'`
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `HaiCommonError.NOT_FOUND.code` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.notFound()
+ * void response.status
+ * ```
+ */
+declare function notFound(message?: string, requestId?: string): Response;
+/**
+ * 创建 409 Conflict 响应
+ *
+ * @param message - 冲突描述（如重复创建等）
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `HaiCommonError.CONFLICT.code` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.conflict('Already updated')
+ * void response.status
+ * ```
+ */
+declare function conflict(message: string, requestId?: string): Response;
+/**
+ * 创建 422 Unprocessable Entity 响应（验证错误）
+ *
+ * @param errors - 字段级别的验证错误列表
+ * @param requestId - 可选请求 ID
+ * @returns error code 为 `HaiCommonError.VALIDATION_ERROR.code`，cause 仅包含 field/message
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.validationError([{ field: 'title', message: 'Title is required' }])
+ * void response.status
+ * ```
+ */
+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 为 `HaiCommonError.INTERNAL_ERROR.code` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.internalError()
+ * void response.status
+ * ```
+ */
+declare function internalError(message?: string, requestId?: string): Response;
+/**
+ * 创建重定向响应
+ *
+ * @param url - 目标 URL
+ * @param status - HTTP 状态码，默认 302；常用 303（POST 后重定向）
+ * @returns 带 `Location` 头的空 body Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.redirect('/articles', 303)
+ * void response.status
+ * ```
+ */
+declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+/**
+ * 将 HaiResult<T> 转换为标准 API Response
+ *
+ * 成功时返回 200 ok(data)，失败时从 error 对象中提取 code、message，
+ * 并根据 httpStatusMap 或错误定义映射 HTTP 状态码；未知状态按 500 安全处理。
+ *
+ * @param result - core HaiResult 对象（{ success, data } 或 { success: false, error }）
+ * @param httpStatusMap - 模块导出的错误码 → HTTP 状态码映射表（如 IamErrorHttpStatus）
+ * @param requestId - 可选请求 ID，用于链路追踪
+ * @returns 标准化 JSON Response
+ * @example
+ * ```ts
+ * import { err, HaiCommonError, type HaiResult } from '@h-ai/core'
+ * import { kit } from '@h-ai/kit'
+ *
+ * function respond(result: HaiResult<{ id: string }>): Response {
+ *   return kit.response.fromResult(result)
+ * }
+ * const response = kit.response.fromResult(err(HaiCommonError.NOT_FOUND, 'Article missing'))
+ * void response.status
+ * ```
+ */
+declare function fromResult<T>(result: HaiResult<T>, httpStatusMap?: Record<number | string, number>, requestId?: string): Response;
+/**
+ * 按模块错误的 HTTP 状态构建安全的统一 API 错误响应。
+ * @param haiError - 包含 code、message 和可选 httpStatus 的模块错误。
+ * @param requestId - 可选的请求追踪标识。
+ * @returns 包含统一错误结构和对应 HTTP 状态的 Response。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.fromError({ code: 'app:articles:001', message: 'Article missing', httpStatus: 404 })
+ * void response.status
+ * ```
+ */
+declare function fromError(haiError: HaiError, requestId?: string): Response;
+
+/**
+ * @h-ai/kit — 请求数据验证
+ *
+ * 基于 Zod 的请求数据验证工具，支持表单/JSON Body、URL 查询参数与路由参数。
+ * Zod 默认错误消息的本地化规则委托给 `core.zodValidation`，避免 kit / serv
+ * 等模块重复维护同一套 issue 解析与消息映射逻辑；模块前缀映射也统一交给
+ * `core.zodValidation.createPrefixedZodMessageGetter()` 处理。
+ * 每种数据源都提供两类 API：
+ * - 安全返回：`FormValidationResult`
+ * - 失败抛出：`OrFail`（抛出 `Response`，由 kit.handler 作为 API 控制流处理）
+ * @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
+ * const schema = zod.object({ title: zod.string().min(1) })
+ * const result = await validateFormOrFail(new Request('https://app.example.com/api', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'Example' }) }), schema)
+ * // 校验失败抛出 Response，由框架错误边界透传。
+ * void result.title
+ * ```
+ */
+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 schema = zod.object({ title: zod.string().min(1) })
+ * const result = validateQueryOrFail(new URL('https://app.example.com/articles?title=Example'), schema)
+ * // 校验失败抛出 Response，由框架错误边界透传。
+ * void result.title
+ * ```
+ */
+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 schema = zod.object({ title: zod.string().min(1) })
+ * const result = validateParamsOrFail({ title: 'Example' }, schema)
+ * // 校验失败抛出 Response，由框架错误边界透传。
+ * void result.title
+ * ```
+ */
+declare function validateParamsOrFail<T extends z.ZodType>(params: Record<string, string>, schema: T): z.infer<T>;
+/**
+ * 路径参数 id 校验 Schema
+ *
+ * 验证 `event.params.id` 为非空字符串。
+ * @example
+ * ```ts
+ * import { IdParamSchema } from '@h-ai/kit'
+ *
+ * const value = IdParamSchema.parse({ id: 'article_1' })
+ * void value
+ * ```
+ */
+declare const IdParamSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * 通用分页查询参数 Schema
+ *
+ * 包含 page（默认 1）、pageSize（默认 20，上限 100）、search（可选）。
+ * 可通过 `.extend()` 扩展业务字段。
+ * @example
+ * ```ts
+ * import { PaginationQuerySchema } from '@h-ai/kit'
+ *
+ * const value = PaginationQuerySchema.parse({ page: '1', pageSize: '20' })
+ * void value
+ * ```
+ */
+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>;
+
+/**
+ * @h-ai/kit — 速率限制中间件
+ *
+ * 以首个成功请求为起点的固定窗口限流；后续计数不延长窗口。
+ * 内置内存存储（`MemoryRateLimitStore`），并支持通过 `RateLimitStore` 接入
+ * Redis 等外部存储后端。
+ * @module kit-ratelimit
+ */
+
+/**
+ * 速率限制存储条目
+ * @example
+ * ```ts
+ * import type { RateLimitEntry } from '@h-ai/kit'
+ *
+ * const value: RateLimitEntry = { count: 1, resetAt: Date.now() + 60_000 }
+ * void value
+ * ```
+ */
+interface RateLimitEntry {
+    /** 当前窗口内的请求次数 */
+    count: number;
+    /** 窗口重置时间戳（ms） */
+    resetAt: number;
+}
+/**
+ * 原子固定窗口计数器；故障抛错由中间件转为503，禁止读改写回退。
+ * @example
+ * ```ts
+ * import type { RateLimitStore } from '@h-ai/kit'
+ *
+ * async function count(store: RateLimitStore) {
+ *   return store.increment('client_1', 60_000)
+ * }
+ * ```
+ */
+interface RateLimitStore {
+    /** shared要求共享后端；memory仅限显式开发/测试。 */
+    readonly scope: 'shared' | 'memory';
+    /** 原子计数并保留首次请求的窗口，返回提交后的计数/重置点。 */
+    increment: (key: string, windowMs: number) => Promise<RateLimitEntry> | RateLimitEntry;
+}
+/**
+ * 共享缓存的最小结构契约；使用其单键CAS与服务端TTL，不使用锁或客户端到期清零。
+ * @example
+ * ```ts
+ * import type { RateLimitCache } from '@h-ai/kit'
+ * import { cache } from '@h-ai/cache'
+ *
+ * const backend: RateLimitCache = cache
+ * void backend
+ * ```
+ */
+interface RateLimitCache {
+    readonly config: {
+        type: string;
+    } | null;
+    readonly kv: {
+        get: <T>(key: string) => Promise<HaiResult<T | null>>;
+        compareAndSwap: (key: string, expected: RateLimitEntry | undefined, value: RateLimitEntry, options: {
+            px?: number;
+            keepTtl?: boolean;
+        }) => Promise<HaiResult<boolean>>;
+    };
+}
+/**
+ * 内存速率限制存储
+ *
+ * 基于 Map 实现，仅用于单进程开发/测试；每次请求最多扫描 64 项过期窗口，
+ * 不持有定时器。最多 10000 项，容量耗尽时拒绝新 key，不驱逐有效计数以免绕过限流。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * // 仅开发/测试；丢弃引用即可回收，无内部定时器。
+ * const store = kit.middleware.createMemoryRateLimitStore()
+ * void store.increment('client_1', 60_000)
+ * ```
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    readonly scope: "memory";
+    private store;
+    private cleanupCursor;
+    /**
+     * 有界惰性回收；保留迭代位置，避免每次从头扫描使尾部过期项永久滞留。
+     * @param now - 当前请求时间，等于 resetAt 时窗口已经失效。
+     */
+    private prune;
+    /**
+     * 原子自增（内存实现为同步操作，天然原子）
+     *
+     * @param key - 限流键
+     * @param windowMs - 窗口时长
+     * @returns 自增后的快照，修改返回对象不会改变已保存的计数。
+     * @throws 新 key 超出容量或期限非法；中间件将其转换为 503。
+     * @example store.increment('client', 60_000)
+     */
+    increment(key: string, windowMs: number): RateLimitEntry;
+}
+
+/**
+ * @h-ai/kit — 类型定义
+ *
+ * SvelteKit 集成相关类型
+ * @module kit-types
+ */
+
+/**
+ * 当前请求的认证 Cookie 写入契约；不持有跨请求状态。
+ * @example
+ * ```ts
+ * import type { AuthCookieWriter } from '@h-ai/kit'
+ * import { kit } from '@h-ai/kit'
+ *
+ * async function signOut(cookies: AuthCookieWriter) {
+ *   const result = await kit.auth.logout(cookies)
+ *   return result.success
+ * }
+ * ```
+ */
+interface AuthCookieWriter {
+    set: (name: string, value: string, options: {
+        path: string;
+        httpOnly: boolean;
+        sameSite: 'lax' | 'strict' | 'none';
+        secure: boolean;
+        maxAge?: number;
+    }) => void;
+    delete: (name: string, options: {
+        path: string;
+    }) => void;
+}
+/**
+ * Kit 服务端公开命名空间；消费者声明只引用公开类型，不暴露内部函数入口。
+ * @example
+ * ```ts
+ * import type { KitFunctions } from '@h-ai/kit'
+ * import { kit } from '@h-ai/kit'
+ *
+ * const runtime: KitFunctions = kit
+ * const response = runtime.response.ok({ ready: true })
+ * void response.status
+ * ```
+ */
+interface KitFunctions {
+    createFeedbackHandler: typeof createFeedbackHandler;
+    middleware: {
+        rateLimit: (config: RateLimitConfig) => Middleware;
+        createCacheRateLimitStore: (backend: RateLimitCache, options: {
+            namespace: string;
+            allowMemory?: boolean;
+        }) => RateLimitStore;
+        createMemoryRateLimitStore: () => MemoryRateLimitStore;
+    };
+    createHandle: typeof createHandle;
+    sequence: typeof sequence;
+    handler: typeof handler;
+    guard: {
+        requireSensitive: typeof requireSensitiveOperation;
+        require: typeof requirePermission;
+        check: typeof hasPermission;
+    };
+    response: {
+        ok: typeof ok;
+        created: typeof created;
+        noContent: typeof noContent;
+        error: typeof error;
+        badRequest: typeof badRequest;
+        unauthorized: typeof unauthorized;
+        forbidden: typeof forbidden;
+        notFound: typeof notFound;
+        conflict: typeof conflict;
+        validationError: typeof validationError;
+        internalError: typeof internalError;
+        redirect: typeof redirect;
+        fromResult: typeof fromResult;
+        fromError: typeof fromError;
+    };
+    validate: {
+        body: typeof validateFormOrFail;
+        query: typeof validateQueryOrFail;
+        params: typeof validateParamsOrFail;
+        IdParamSchema: typeof IdParamSchema;
+        PaginationQuerySchema: typeof PaginationQuerySchema;
+    };
+    client: {
+        create: typeof createKitClient;
+        createAuthActions: typeof createKitAuthActions;
+        installBrowserTransport: typeof installBrowserTransport;
+        installBrowserTransportFetch: typeof installBrowserTransportFetch;
+    };
+    auth: {
+        publicPaths: string[];
+        createApi: typeof createAuthApi;
+        login: (cookies: AuthCookieWriter, credentials: PasswordCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
+        loginWithOtp: (cookies: AuthCookieWriter, credentials: OtpCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
+        loginWithLdap: (cookies: AuthCookieWriter, credentials: LdapCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
+        loginWithApiKey: (cookies: AuthCookieWriter, credentials: ApiKeyCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
+        registerAndLogin: (cookies: AuthCookieWriter, options: RegisterOptions, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
+        logout: (cookies: AuthCookieWriter, accessToken?: string | null) => Promise<HaiResult<void>>;
+        setBrowserToken: (token: string) => void;
+        clearBrowserToken: () => void;
+    };
+    crud: {
+        define: typeof defineCrud;
+    };
+    i18n: {
+        setLocale: (locale: string) => void;
+        runWithLocale: typeof core.i18n.runWithLocale;
+    };
+}
+/**
+ * 浏览器实际可用的 Kit 命名空间；不含服务端认证、Hook 或中间件。
+ * @example
+ * ```ts
+ * import type { BrowserKitFunctions } from '@h-ai/kit'
+ * import { kit } from '@h-ai/kit'
+ *
+ * const browser: BrowserKitFunctions = kit
+ * browser.auth.clearBrowserToken()
+ * ```
+ */
+interface BrowserKitFunctions {
+    client: {
+        create: typeof createKitClient;
+        createAuthActions: typeof createKitAuthActions;
+        installBrowserTransport: typeof installBrowserTransport;
+        installBrowserTransportFetch: typeof installBrowserTransportFetch;
+    };
+    crud: {
+        define: typeof defineCrud;
+    };
+    auth: {
+        setBrowserToken: (token: string) => void;
+        clearBrowserToken: () => void;
+    };
+    i18n: {
+        setLocale: (locale: string) => void;
+    };
+}
+/**
+ * 服务器监听配置（对应 `config/_kit.yml` 的 `server`）。
+ * @example
+ * ```ts
+ * import type { KitServerConfig } from '@h-ai/kit'
+ *
+ * const value: KitServerConfig = { host: '127.0.0.1', port: 3000 }
+ * void value
+ * ```
+ */
+interface KitServerConfig {
+    readonly host: string;
+    readonly port: number;
+}
+/**
+ * `config/_kit.yml` 中的服务器监听输入类型。
+ * @example
+ * ```ts
+ * import type { KitServerConfigInput } from '@h-ai/kit'
+ *
+ * const value: KitServerConfigInput = { port: 4000 }
+ * void value
+ * ```
+ */
+type KitServerConfigInput = Partial<KitServerConfig>;
+/**
+ * `config/_kit.yml` 中的 transport 配置。
+ * @example
+ * ```ts
+ * import type { KitTransportConfig } from '@h-ai/kit'
+ *
+ * const value: KitTransportConfig = { keyExchangePath: '/api/_hai/key-exchange', excludePaths: ['/api/health'] }
+ * void value
+ * ```
+ */
+interface KitTransportConfig {
+    /** 双向明文 UTF-8 字节上限；省略使用 1 MiB，范围 1 KiB～64 MiB。 */
+    readonly maxPlaintextBytes?: number;
+    /** 请求时间允许领先服务器的秒数，默认 30，整数范围 0～300。 */
+    readonly maxFutureSkewSeconds?: number;
+    /** 请求从签发起的有效秒数，默认 300，整数范围 1～600。 */
+    readonly maxRequestAgeSeconds?: number;
+    /** 按完整路径段匹配的明文容量；* 匹配单段。 */
+    readonly routePlaintextBytes?: Readonly<Record<string, number>>;
+    readonly keyExchangePath: `/${string}`;
+    readonly excludePaths: readonly `/${string}`[];
+}
+/**
+ * `config/_kit.yml` 的顶层配置结构。
+ * @example
+ * ```ts
+ * import type { KitConfig } from '@h-ai/kit'
+ *
+ * const value: KitConfig = { server: { host: '127.0.0.1', port: 3000 }, transport: false, trustedProxies: 'auto', access: false }
+ * void value
+ * ```
+ */
+interface KitConfig {
+    readonly server: KitServerConfig;
+    readonly transport: false | KitTransportConfig;
+    /** auto 仅在受管私有容器入口采用容器网段；普通宿主忽略转发头。 */
+    readonly trustedProxies: TrustedProxies;
+    /** 每次请求的地址/时间/路径限制，默认 false；不会限制由静态服务器直接提供的资源。 */
+    readonly access: RequestAccessConfigInput;
+}
+/**
+ * `config/_kit.yml` 中的 transport 输入类型。
+ * @example
+ * ```ts
+ * import type { KitTransportConfigInput } from '@h-ai/kit'
+ *
+ * const value: KitTransportConfigInput = { excludePaths: ['/api/health'] }
+ * void value
+ * ```
+ */
+type KitTransportConfigInput = Partial<{
+    readonly maxPlaintextBytes: number | 'auto';
+    readonly maxFutureSkewSeconds: number;
+    readonly maxRequestAgeSeconds: number;
+    readonly routePlaintextBytes: Readonly<Record<string, number>>;
+    readonly keyExchangePath: `/${string}`;
+    readonly excludePaths: readonly `/${string}`[];
+}>;
+/**
+ * `config/_kit.yml` 的顶层输入类型。
+ * @example
+ * ```ts
+ * import type { KitConfigInput } from '@h-ai/kit'
+ *
+ * const value: KitConfigInput = { transport: false }
+ * void value
+ * ```
+ */
+interface KitConfigInput {
+    readonly server?: KitServerConfigInput;
+    readonly transport?: false | KitTransportConfigInput;
+    readonly trustedProxies?: TrustedProxies;
+    readonly access?: RequestAccessConfigInput;
+}
+/**
+ * 浏览器可接收的 Kit 公共配置，仅包含传输协议路径和开关。
+ * @example
+ * ```ts
+ * import type { KitPublicConfig } from '@h-ai/kit'
+ * const config: KitPublicConfig = { transport: false }
+ * ```
+ */
+type KitPublicConfig = Pick<KitConfig, 'transport'>;
+/**
+ * kit.auth 认证操作（由 createHandle auth.operations 注入）
+ *
+ * 注入后，kit.auth.login / kit.auth.logout 等函数自动委托到 iam.auth 对应方法。
+ * 传入 `iam.auth` 即可，kit 会自动提取所需方法。
+ * @example
+ * ```ts
+ * import type { AuthOperations } from '@h-ai/kit'
+ * import { iam } from '@h-ai/iam'
+ *
+ * // 在 IAM 初始化后注入其当前操作对象。
+ * const operations: AuthOperations = iam.auth
+ * void operations
+ * ```
+ */
+type AuthOperations = Pick<AuthnOperations, 'login' | 'loginWithOtp' | 'loginWithLdap' | 'loginWithApiKey' | 'registerAndLogin' | 'logout'>;
+/**
+ * 认证操作提供器：支持直接传对象或按需返回最新对象的工厂函数
+ * @example
+ * ```ts
+ * import type { AuthOperationsProvider } from '@h-ai/kit'
+ * import { iam } from '@h-ai/iam'
+ *
+ * const operations: AuthOperationsProvider = () => iam.auth
+ * void operations
+ * ```
+ */
+type AuthOperationsProvider = AuthOperations | (() => AuthOperations);
+/**
+ * 会话数据最小接口
+ *
+ * 守卫和权限检查函数所需的最小会话形状。
+ * 应用层扩展的 session（如添加 displayName / avatarUrl 等字段）
+ * 只要包含此接口的字段即可直接传入守卫函数，无需类型断言。
+ * @example
+ * ```ts
+ * import type { SessionLike } from '@h-ai/kit'
+ *
+ * const value: SessionLike = { userId: 'user_1', roles: ['editor'], permissions: ['article:read'] }
+ * void value
+ * ```
+ */
+interface SessionLike {
+    /** 用户 ID */
+    userId: string;
+    /** 角色列表 */
+    roles: string[];
+    /** 权限列表 */
+    permissions: string[];
+    /** 允许任意扩展字段 */
+    [key: string]: unknown;
+}
+/**
+ * 用户会话数据
+ *
+ * 在 Handle Hook 中通过 `validateSession` 解析后注入 `event.locals.session`。
+ * 守卫和中间件通过此结构判断用户身份、角色与权限。
+ *
+ * 应用层可通过 `& { displayName: string }` 等方式扩展，
+ * 扩展后的类型自动兼容所有守卫和权限检查函数（它们接受 `SessionLike`）。
+ * @example
+ * ```ts
+ * import type { SessionData } from '@h-ai/kit'
+ *
+ * const value: SessionData = { userId: 'user_1', username: 'alice', roles: ['editor'], permissions: ['article:read'] }
+ * void value
+ * ```
+ */
+interface SessionData {
+    /** 用户 ID */
+    userId: string;
+    /** 用户名 */
+    username?: string;
+    /** 角色列表 */
+    roles: string[];
+    /** 权限列表 */
+    permissions: string[];
+    /** 自定义数据 */
+    data?: Record<string, unknown>;
+    /** 允许任意扩展字段 */
+    [key: string]: unknown;
+}
+/**
+ * 扩展的请求事件
+ *
+ * 在 SvelteKit 原生 `RequestEvent` 基础上注入会话和请求 ID。
+ * @example
+ * ```ts
+ * import type { HaiRequestEvent } from '@h-ai/kit'
+ *
+ * function requestLabel(event: HaiRequestEvent) {
+ *   return { requestId: event.requestId, userId: event.session?.userId }
+ * }
+ * ```
+ */
+interface HaiRequestEvent extends RequestEvent {
+    /** 会话数据 */
+    session?: SessionData;
+    /** 请求 ID */
+    requestId: string;
+}
+/**
+ * 中间件上下文
+ *
+ * 由 `createHandle` 构建，传递给所有中间件函数。
+ * 包含当前请求事件、已解析的会话以及请求唯一 ID。
+ * @example
+ * ```ts
+ * import type { MiddlewareContext } from '@h-ai/kit'
+ *
+ * function requestLabel(context: MiddlewareContext) {
+ *   return context.event.url.pathname + ':' + context.requestId
+ * }
+ * ```
+ */
+interface MiddlewareContext {
+    /** 请求事件 */
+    event: RequestEvent;
+    /** 会话数据 */
+    session?: SessionData;
+    /** 请求 ID */
+    requestId: string;
+}
+/**
+ * 中间件函数
+ *
+ * 遵循洋葱模型：调用 `next()` 前执行前置逻辑，调用后执行后置逻辑。
+ * @example
+ * ```ts
+ * import type { Middleware } from '@h-ai/kit'
+ *
+ * const value: Middleware = async (_context, next) => { const response = await next(); response.headers.set('X-Example', 'enabled'); return response }
+ * void value
+ * ```
+ */
+type Middleware = (context: MiddlewareContext, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * 路由守卫结果
+ *
+ * 守卫函数必须返回此结构。`allowed: true` 表示放行，否则根据
+ * `redirect` / `message` / `status` 决定拦截行为。
+ * @example
+ * ```ts
+ * import type { GuardResult } from '@h-ai/kit'
+ *
+ * const value: GuardResult = { allowed: false, status: 403 }
+ * void value
+ * ```
+ */
+interface GuardResult {
+    /** 是否允许访问 */
+    allowed: boolean;
+    /** 重定向 URL（拒绝时） */
+    redirect?: string;
+    /** 错误消息（拒绝时） */
+    message?: string;
+    /** HTTP 状态码 */
+    status?: number;
+}
+/**
+ * 路由守卫函数
+ *
+ * 接收请求事件与可选会话，返回 `GuardResult`（同步或异步均可）。
+ * @example
+ * ```ts
+ * import type { RouteGuard } from '@h-ai/kit'
+ *
+ * const value: RouteGuard = (_event, session) => ({ allowed: session?.permissions.includes('article:read') ?? false, status: 403 })
+ * void value
+ * ```
+ */
+type RouteGuard = (event: RequestEvent, session?: SessionData) => Promise<GuardResult> | GuardResult;
+/**
+ * 守卫配置
+ *
+ * 在 `createHandle({ guards })` 中使用。
+ * `paths` 支持 `/*` 和 `/**` 通配符，`exclude` 优先于 `paths`。
+ * @example
+ * ```ts
+ * import type { GuardConfig } from '@h-ai/kit'
+ *
+ * const value: GuardConfig = { paths: ['/admin/**'], guard: (_event, session) => ({ allowed: Boolean(session) }) }
+ * void value
+ * ```
+ */
+interface GuardConfig {
+    /** 守卫函数 */
+    guard: RouteGuard;
+    /** 适用路径（glob 模式） */
+    paths?: string[];
+    /** 排除路径 */
+    exclude?: string[];
+}
+/**
+ * 认证配置
+ *
+ * 在 `HandleConfig.auth` 中使用，自动完成：
+ * 1. 从 Bearer header / Cookie 提取 Token
+ * 2. 调用 verifyToken 恢复会话
+ * 3. 根据 protectedPaths / publicPaths 自动生成路由守卫
+ *
+ * API 路径（以 `/api/` 开头）未认证时返回 401 JSON；
+ * 非 API 路径未认证时重定向到 `loginUrl`（若配置）或返回 401。
+ * @example
+ * ```ts
+ * import type { HandleAuthConfig } from '@h-ai/kit'
+ *
+ * const value: HandleAuthConfig = { verifyToken: async () => null, protectedPaths: ['/admin/**'], loginUrl: '/auth/login' }
+ * void value
+ * ```
+ */
+interface HandleAuthConfig {
+    /** 令牌验证函数，返回 SessionData 或 null */
+    verifyToken: (token: string) => Promise<SessionData | null>;
+    /**
+     * 认证操作。
+     *
+     * - 直接对象：`operations: iam.auth`
+     * - 工厂函数：`operations: () => iam.auth`（推荐，避免模块加载阶段捕获旧引用）
+     */
+    operations?: AuthOperationsProvider;
+    /** 未认证时 UI 路由重定向地址（如 `'/auth/login'`） */
+    loginUrl?: string;
+    /** Token Cookie 名（默认 `'hai_access_token'`） */
+    cookieName?: string;
+    /** 需要认证的路径（支持 `/*` `/**` 通配符） */
+    protectedPaths?: string[];
+    /** 免认证的路径（优先于 protectedPaths） */
+    publicPaths?: string[];
+}
+/**
+ * Handle Hook 配置
+ *
+ * 传给 `kit.createHandle()` 的配置。
+ *
+ * 自动完成：
+ * 1. 生成 requestId 并注入 `event.locals`
+ * 2. 根据 `auth` 配置解析会话
+ * 3. 执行路由守卫
+ * 4. 执行中间件链（logging / rateLimit / 自定义）
+ * 5. 调用 resolve + 附加 `X-Request-Id` 响应头
+ * @example
+ * ```ts
+ * import type { HandleConfig } from '@h-ai/kit'
+ *
+ * const value: HandleConfig = { logging: true, auth: { verifyToken: async () => null, protectedPaths: ['/admin/**'] } }
+ * void value
+ * ```
+ */
+interface HandleConfig {
+    /** 可信入口地址；auto 只信任受管私有容器网段，空数组忽略转发头。 */
+    trustedProxies?: TrustedProxies;
+    /** 每次请求的 IP/时间/路径策略；独立文件在创建 Handle 时读取并验证一次。 */
+    access?: RequestAccessConfigInput;
+    /**
+     * 认证配置
+     *
+     * 提供后自动完成 Token 解析、会话恢复、路由守卫等。
+     * 不提供则不做认证处理。
+     */
+    auth?: HandleAuthConfig;
+    /**
+     * 速率限制配置
+     *
+     * 提供对象启用速率限制；设为 `false` 显式禁用。
+     * 不提供则不开启速率限制。
+     */
+    rateLimit?: Omit<RateLimitConfig, 'windowMs' | 'maxRequests'> & {
+        windowMs?: number;
+        maxRequests?: number;
+    } | false;
+    /**
+     * 请求日志配置
+     *
+     * - `true`（默认）：启用日志中间件
+     * - `{ logBody: true }`：启用并记录请求体
+     * - `false`：禁用日志
+     */
+    logging?: boolean | {
+        logBody?: boolean;
+    };
+    /**
+     * 加密配置（传输加密 + Cookie 加密）
+     *
+     * 启用后 kit 自动在 Handle 中完成：
+     * - 传输加密：请求体解密 / 响应体加密 / 密钥交换端点
+     * - Cookie 加密：对指定 Cookie 的 get/set 使用 SM4-CBC 加解密并验证 HMAC-SHA256 认证
+     */
+    crypto?: HookCryptoConfig;
+    /** 自定义错误处理（不提供则使用内置的 500 JSON 响应） */
+    onError?: (error: unknown, event: RequestEvent) => Response | Promise<Response>;
+    /** 自定义守卫（在 auth 自动守卫之后执行） */
+    guards?: GuardConfig[];
+    /** 自定义中间件（在内置 logging / rateLimit 之后执行） */
+    middleware?: Middleware[];
+    /**
+     * A2A 协议集成
+     *
+     * 传入 `ai.a2a` 操作对象后，自动挂载 Agent Card 发现端点和 JSON-RPC 处理端点。
+     *
+     * - 简单模式：`a2a: ai.a2a`（使用默认路径）
+     * - 配置模式：`a2a: { operations: ai.a2a, rpcPath: '/api/a2a' }`
+     */
+    a2a?: HandleA2AOperations | HandleA2AConfig;
+}
+/**
+ * A2A 操作接口（用于 Handle 集成）
+ *
+ * 与 `ai.a2a` 结构兼容，可直接传入 `ai.a2a` 对象。
+ * @example
+ * ```ts
+ * import type { HandleA2AOperations } from '@h-ai/kit'
+ * import { ai } from '@h-ai/ai'
+ *
+ * function operationsAfterInit(): HandleA2AOperations { return ai.a2a }
+ * ```
+ */
+interface HandleA2AOperations {
+    /** 获取 Agent Card（返回 HaiResult 对象） */
+    getAgentCard: () => {
+        success: boolean;
+        data?: unknown;
+        error?: unknown;
+    };
+    /** 处理 JSON-RPC 请求 */
+    handleRequest: (body: unknown, context?: Record<string, unknown>) => Promise<{
+        streaming: boolean;
+        body?: unknown;
+        stream?: AsyncGenerator<unknown, void, undefined>;
+    }>;
+}
+/**
+ * A2A Handle 配置（高级模式）
+ * @example
+ * ```ts
+ * import type { HandleA2AConfig } from '@h-ai/kit'
+ * import { ai } from '@h-ai/ai'
+ *
+ * function configAfterInit(): HandleA2AConfig { return { operations: ai.a2a, authenticate: async () => null } }
+ * ```
+ */
+interface HandleA2AConfig {
+    /** A2A 操作接口（通常传入 `ai.a2a`） */
+    operations: HandleA2AOperations;
+    /** Agent Card 端点路径（默认 `/.well-known/agent-card.json`） */
+    cardPath?: string;
+    /** JSON-RPC 端点路径（默认 `/a2a`） */
+    rpcPath?: string;
+    /**
+     * A2A 认证
+     *
+     * - `'apiKey'`：使用 IAM API Key 认证（读取 Agent Card.securitySchemes.apiKey）
+     * - 函数：自定义认证回调；返回 null/undefined 拒绝请求（401）
+     * 未配置此项才允许匿名请求。
+     */
+    authenticate?: 'apiKey' | ((event: RequestEvent) => Promise<Record<string, unknown> | null | undefined>);
+}
+/**
+ * 传输加密详细配置
+ * @example
+ * ```ts
+ * import type { TransportEncryptionOptions } from '@h-ai/kit'
+ * import type { TransportServerKeyRing, TransportKeyStore } from '@h-ai/crypto'
+ *
+ * function transport(serverKeyRing: TransportServerKeyRing, keyStore: TransportKeyStore): TransportEncryptionOptions {
+ *   return { serverKeyRing, keyStore, excludePaths: ['/api/health'] }
+ * }
+ * ```
+ */
+interface TransportEncryptionOptions {
+    /** 宿主构建挂载目录，默认空字符串；SvelteKit 传入 paths.relative=false 时的 resolve('/').replace(/\/$/, '')。 */
+    basePath?: string;
+    /** 双向业务明文 UTF-8 字节上限；默认 1 MiB，整数范围 1 KiB～64 MiB。 */
+    maxPlaintextBytes?: number;
+    /** 请求时间允许领先服务器的秒数，默认 30，整数范围 0～300。 */
+    maxFutureSkewSeconds?: number;
+    /** 请求从签发起的有效秒数，默认 300，整数范围 1～600。 */
+    maxRequestAgeSeconds?: number;
+    /** 路由明文容量；* 匹配一个完整路径段。 */
+    routePlaintextBytes?: Readonly<Record<string, number>>;
+    /** 受管服务端版本化密钥环，不进入公开 YAML/客户端配置。 */
+    serverKeyRing: TransportServerKeyRing;
+    /** 密钥交换端点路径（默认 `'/api/_hai/key-exchange'`） */
+    keyExchangePath?: string;
+    /** 排除路径（不加密），支持精确匹配和前缀匹配 */
+    excludePaths?: readonly string[];
+    /** 共享客户端公钥存储；适用于多节点部署。 */
+    keyStore: TransportKeyStore;
+}
+/**
+ * Handle Hook 加密配置
+ *
+ * 在 `kit.createHandle({ crypto: { ... } })` 中使用。
+ * @example
+ * ```ts
+ * import type { HookCryptoConfig, TransportEncryptionOptions } from '@h-ai/kit'
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function config(transport: TransportEncryptionOptions): HookCryptoConfig { return { crypto, transport } }
+ * ```
+ */
+interface HookCryptoConfig {
+    /** 注入 @h-ai/crypto 实例 */
+    crypto: CryptoFunctions;
+    /**
+     * 启用传输加密。
+     * - `false` 或省略：关闭
+     * - 对象：必填受管 serverKeyRing / keyStore，可附加公开路径配置
+     */
+    transport?: false | TransportEncryptionOptions;
+    /**
+     * 需要加密的 Cookie 名称列表
+     *
+     * 列出的 Cookie 在 set 时自动 SM4-CBC 加密，get 时自动解密。
+     */
+    encryptedCookies?: string[];
+    /**
+     * Cookie 加密密钥（32 字符十六进制 = 16 字节 SM4 密钥）
+     *
+     * 如不提供，则从环境变量 `HAI_KIT_COOKIE_KEY` 读取。
+     * 配置了 `encryptedCookies` 但两者都未设置时，`kit.createHandle()` 会立即抛出配置错误，
+     * 避免受保护 Cookie 静默降级为明文。
+     */
+    cookieEncryptionKey?: string;
+}
+/**
+ * API 响应包装
+ *
+ * `kit.response.*` 系列函数统一返回此结构的 JSON 响应。
+ * 成功时 `success: true` 且 `data` 有值；失败时 `success: false` 且 `error` 有值。
+ * @example
+ * ```ts
+ * import type { ApiResponse } from '@h-ai/kit'
+ *
+ * const value: ApiResponse<{ id: string }> = { success: true, data: { id: 'article_1' } }
+ * void value
+ * ```
+ */
+interface ApiResponse<T = unknown> {
+    /** 是否成功 */
+    success: boolean;
+    /** 数据 */
+    data?: T;
+    /** 错误信息 */
+    error?: {
+        code: string;
+        message: string;
+        traceId?: string;
+        /** 对应 HTTP 状态 */
+        httpStatus?: number;
+        /** 仅含已本地化 field/message 的字段校验信息 */
+        cause?: HaiError['cause'];
+        /** 经公开边界脱敏的扩展信息 */
+        ext?: HaiError['ext'];
+        details?: unknown;
+    };
+    /** 请求 ID */
+    requestId?: string;
+}
+/**
+ * 表单验证错误
+ *
+ * 由 `kit.validate.*` 在校验失败时返回。
+ * `field` 使用点号路径（如 `'address.city'`），`_` 表示全局错误。
+ * @example
+ * ```ts
+ * import type { FormError } from '@h-ai/kit'
+ *
+ * const value: FormError = { field: 'title', message: 'Title is required' }
+ * void value
+ * ```
+ */
+interface FormError {
+    /** 字段名 */
+    field: string;
+    /** 错误消息 */
+    message: string;
+}
+/**
+ * 表单验证结果
+ *
+ * @template T - Zod schema 推导出的数据类型
+ * @example
+ * ```ts
+ * import type { FormValidationResult } from '@h-ai/kit'
+ *
+ * const value: FormValidationResult<{ title: string }> = { valid: true, data: { title: 'Example' }, errors: [] }
+ * void value
+ * ```
+ */
+interface FormValidationResult<T> {
+    /** 是否有效 */
+    valid: boolean;
+    /** 解析后的数据 */
+    data?: T;
+    /** 错误列表 */
+    errors: FormError[];
+}
+/**
+ * 速率限制配置
+ *
+ * 基于可插拔原子存储的固定窗口限流。超限后返回 429 状态码与 `Retry-After` 响应头。
+ * 必须显式传入 store；生产使用共享计数器，故障返回503。
+ * @example
+ * ```ts
+ * import type { RateLimitConfig } from '@h-ai/kit'
+ * import { kit } from '@h-ai/kit'
+ * import { cache } from '@h-ai/cache'
+ *
+ * const config: RateLimitConfig = { windowMs: 60_000, maxRequests: 100, store: kit.middleware.createCacheRateLimitStore(cache, { namespace: 'api' }) }
+ * void config
+ * ```
+ */
+interface RateLimitConfig {
+    /** 时间窗口 (ms) */
+    windowMs: number;
+    /** 最大请求数 */
+    maxRequests: number;
+    /** 自定义 key 生成 */
+    keyGenerator?: (event: RequestEvent) => string;
+    /** 超限处理 */
+    onLimitReached?: (event: RequestEvent) => Response;
+    /**
+     * 自定义存储实现
+     *
+     * 必须提供原子 increment；不支持 get+set 回退。共享缓存由调用方初始化和关闭。
+     */
+    store: RateLimitStore;
+}
+/**
+ * CORS 中间件配置
+ *
+ * 配置跨域资源共享策略。预检请求（OPTIONS）自动返回 204。
+ * @example
+ * ```ts
+ * import type { CorsConfig } from '@h-ai/kit'
+ *
+ * const value: CorsConfig = { origin: ['https://app.example.com'], credentials: true }
+ * void value
+ * ```
+ */
+interface CorsConfig {
+    /** 允许的源（支持通配符，如 `*.example.com`） */
+    origin?: string | string[] | ((origin: string) => boolean);
+    /** 允许的方法 */
+    methods?: string[];
+    /** 允许的头 */
+    allowedHeaders?: string[];
+    /** 暴露的头 */
+    exposedHeaders?: string[];
+    /** 是否允许凭证 */
+    credentials?: boolean;
+    /** 预检缓存时间 (秒) */
+    maxAge?: number;
+    /** 是否自动允许 Capacitor WebView origin（默认 true） */
+    capacitor?: boolean;
+}
+
+export { MemoryRateLimitStore as $, IdParamSchema as _, PaginationQuerySchema as a0, defineCrud as a5, matchPermission as a6, resolveOptions as a7, resolveText as a8, createKitAuthActions as v, createKitClient as w, installBrowserTransport as x, installBrowserTransportFetch as y };
+export type { ApiResponse as A, BrowserKitFunctions as B, ClientTransportConfig as C, AuthCookieWriter as D, CrudApiDef as E, FormError as F, GuardConfig as G, HaiRequestEvent as H, CrudFieldDef as I, CrudFieldOption as J, KitClient as K, CrudFieldOptions as L, Middleware as M, CrudFieldType as N, CrudFieldValidation as O, CrudFilterParams as P, CrudOperations as Q, RateLimitConfig as R, SessionData as S, TransportEncryptionOptions as T, CrudPaginatedResult as U, CrudPaginationParams as V, CrudResourceDef as W, CrudTableColumn as X, CrudText as Y, FeedbackHandlerOptions as Z, AuthOperations as a, PermissionGuardConfig as a1, RateLimitCache as a2, RateLimitEntry as a3, RateLimitStore as a4, AuthOperationsProvider as b, CorsConfig as c, FormValidationResult as d, GuardResult as e, HandleA2AConfig as f, HandleA2AOperations as g, HandleAuthConfig as h, HandleConfig as i, HookCryptoConfig as j, KitClientConfig as k, KitConfig as l, KitConfigInput as m, KitPublicConfig as n, KitServerConfig as o, KitServerConfigInput as p, KitTransportConfig as q, KitTransportConfigInput as r, MiddlewareContext as s, RouteGuard as t, SessionLike as u, KitFunctions as z };