@h-ai/kit 0.1.0-alpha8 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -1,19 +1,23 @@
-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 { c as createKitClient, a as createKitAuthActions, i as installBrowserTransport, b as installBrowserTransportFetch, l as login, f as loginWithOtp, g as loginWithLdap, h as loginWithApiKey, r as registerAndLogin, j as logout, s as setBrowserToken, d as clearBrowserToken } from './kit-client-auth-BnhrkzZF.js';
+export { C as ClientTransportConfig, K as KitClient, e as KitClientConfig } from './kit-client-auth-BnhrkzZF.js';
+import { d as defineCrud, s as setAllModulesLocale } from './kit-i18n-EBzZKYN-.js';
+export { C as CrudApiDef, b as CrudFieldDef, c as CrudFieldOption, e as CrudFieldOptions, f as CrudFieldType, g as CrudFieldValidation, h as CrudFilterParams, i as CrudOperations, j as CrudPaginatedResult, k as CrudPaginationParams, l as CrudResourceDef, m as CrudTableColumn, n as CrudText, K as KitConfigSchema, r as resolveKitConfig, a as resolveKitTransportConfig, o as resolveOptions, p as resolveText } from './kit-i18n-EBzZKYN-.js';
+import { S as SessionData, r as SessionLike, h as HandleConfig, s as rateLimitMiddleware, t as createCacheRateLimitStore, u as createMemoryRateLimitStore } from './kit-types-BkNdyKj8.js';
+export { A as ApiResponse, a as AuthOperations, b as AuthOperationsProvider, C as CorsConfig, 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, K as KitConfig, j as KitConfigInput, k as KitPublicConfig, l as KitServerConfig, m as KitServerConfigInput, n as KitTransportConfig, o as KitTransportConfigInput, v as MemoryRateLimitStore, M as Middleware, p as MiddlewareContext, w as RateLimitCache, R as RateLimitConfig, x as RateLimitEntry, y as RateLimitStore, q as RouteGuard, T as TransportEncryptionOptions } from './kit-types-BkNdyKj8.js';
+import { CryptoFunctions } from '@h-ai/crypto';
+export { EncryptedPayload, TransportEncryptionManager, TransportKeyPair } from '@h-ai/crypto';
+import { FeedbackFunctions, FeedbackContext } from '@h-ai/feedback';
+import * as _sveltejs_kit from '@sveltejs/kit';
+import { RequestEvent, Handle, RequestHandler } from '@sveltejs/kit';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiError } from '@h-ai/core';
+import * as zod_v4_core from 'zod/v4/core';
 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';
+import { IamFunctions } from '@h-ai/iam';
+export { A as A2AApiKeyAuthConfig, K as KitA2AHandlerConfig, R as ResolvedA2AConfig } from './kit-a2a-types-4dapztu2.js';
+export { C as CryptoCsrfConfig, a as CryptoServiceLike, E as EncryptedCookieConfig, T as TransportEncryptionConfig, W as WebhookVerifyConfig } from './kit-crypto-types-CXr888wf.js';
+import '@h-ai/api-contract';
 
 /**
  * @h-ai/kit — 认证守卫
@@ -24,6 +28,13 @@ import '@h-ai/iam';
 
 /**
  * 认证守卫配置
+ * @example
+ * ```ts
+ * import type { AuthGuardConfig } from '@h-ai/kit'
+ *
+ * const value: AuthGuardConfig = { apiMode: true }
+ * void value
+ * ```
  */
 interface AuthGuardConfig {
     /** 未登录时重定向 URL（默认 `'/login'`） */
@@ -33,6 +44,13 @@ interface AuthGuardConfig {
 }
 /**
  * 会话守卫配置
+ * @example
+ * ```ts
+ * import type { SessionGuardConfig } from '@h-ai/kit'
+ *
+ * const value: SessionGuardConfig = { validateSession: async () => null }
+ * void value
+ * ```
  */
 interface SessionGuardConfig {
     /** 会话校验函数（通常由应用注入 iam.auth.verifyToken 封装） */
@@ -42,122 +60,6 @@ interface SessionGuardConfig {
     /** 为 `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 — 权限守卫
@@ -168,6 +70,13 @@ declare function conditionalGuard(condition: ConditionFn, guard: RouteGuard): Ro
 
 /**
  * 权限守卫配置
+ * @example
+ * ```ts
+ * import type { PermissionGuardConfig } from '@h-ai/kit'
+ *
+ * const value: PermissionGuardConfig = { permissions: ['article:read'] }
+ * void value
+ * ```
  */
 interface PermissionGuardConfig {
     /** 需要的权限列表（默认 OR 逻辑，满足任一即通过） */
@@ -179,24 +88,6 @@ interface PermissionGuardConfig {
     /** 为 `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;
 /**
  * 匹配权限
  *
@@ -207,6 +98,13 @@ declare function permissionGuard(config: PermissionGuardConfig): RouteGuard;
  * @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;
 /**
@@ -217,85 +115,32 @@ declare function matchPermission(required: string, userPermissions: string[]): b
  * @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。
+ * import { kit } from '@h-ai/kit'
  *
- * @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
- *   // ... 正常逻辑
- * }
+ * const allowed = kit.guard.check({ userId: 'user_1', roles: ['editor'], permissions: ['article:read'] }, 'article:read')
+ * void allowed
  * ```
  */
-declare function assertPermission(session: SessionLike | null | undefined, permission: string): Response | undefined;
+declare function hasPermission(session: SessionLike | null | undefined, permission: string): boolean;
 /**
  * 要求会话具有指定权限，不满足时 throw Response
  *
- * 利用 SvelteKit 控制流机制：throw 的 Response 对象会被框架捕获并直接作为响应返回。
+ * throw 的 Response 对象由 kit.handler 捕获并直接作为 API 响应返回。
  * 搭配 `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 控制流抛出）。
+ * import { kit } from '@h-ai/kit'
  *
- * 适用于 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)
- * }))
+ * kit.guard.require({ userId: 'user_1', roles: ['editor'], permissions: ['article:read'] }, 'article:read') // 拒绝时抛出 Response，由 kit.handler 传递。
  * ```
  */
-declare function withPermission<TEvent extends {
-    locals: Record<string, unknown>;
-}, TReturn>(permission: string, handler: (event: TEvent) => Promise<TReturn>): (event: TEvent) => Promise<TReturn>;
+declare function requirePermission(session: SessionLike | null | undefined, permission: string): void;
 
 /**
  * @h-ai/kit — 角色守卫
@@ -306,6 +151,13 @@ declare function withPermission<TEvent extends {
 
 /**
  * 角色守卫配置
+ * @example
+ * ```ts
+ * import type { RoleGuardConfig } from '@h-ai/kit'
+ *
+ * const value: RoleGuardConfig = { roles: ['editor'] }
+ * void value
+ * ```
  */
 interface RoleGuardConfig {
     /** 需要的角色列表（默认 OR 逻辑，满足任一即通过） */
@@ -317,23 +169,31 @@ interface RoleGuardConfig {
     /** 为 `true` 时返回 JSON 403 而非重定向 */
     apiMode?: boolean;
 }
+
+/** 可选敏感操作再鉴别；由操作入口在现有权限/资源检查之后调用。 */
+
 /**
- * 创建角色守卫
- *
- * 检查用户 `session.roles` 是否满足配置中的角色要求。
- * 未认证时返回 401；角色不匹配时根据 `apiMode` 返回 JSON 403 或重定向。
- *
- * @param config - 角色守卫配置
- * @returns RouteGuard 实例
- *
+ * 要求选定操作携带短期单次再鉴别票据；失败抛出 Response，由 kit.handler 返回。
+ * 不替代已有认证、权限与资源范围守卫；操作 ID 必须由服务端指定。
+ * @param iam - 已初始化的 IAM 服务。
+ * @param event - 当前请求与 Cookie，不能跨请求保存。
+ * @param operation - 当前服务端操作 ID。
+ * @returns 策略关闭、未选操作或证明校验成功时无返回值。
  * @example
  * ```ts
- * guards: [
- *   { guard: kit.guard.role({ roles: ['admin'], apiMode: true }), paths: ['/api/admin/*'] },
- * ]
+ * 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 roleGuard(config: RoleGuardConfig): RouteGuard;
+declare function requireSensitiveOperation(iam: IamFunctions, event: Pick<RequestEvent, 'request' | 'cookies'>, operation: string): Promise<void>;
 
 /**
  * @h-ai/kit — Cookie 加密代理
@@ -344,29 +204,24 @@ declare function roleGuard(config: RoleGuardConfig): RouteGuard;
 
 /**
  * Cookie 加密代理配置
+ * @example
+ * ```ts
+ * import type { CookieProxyConfig } from '@h-ai/kit'
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function config(encryptionKey: string): CookieProxyConfig {
+ *   return { names: new Set(['session']), symmetric: crypto.symmetric, encryptionKey }
+ * }
+ * ```
  */
 interface CookieProxyConfig {
     /** 需要加密的 Cookie 名称集合 */
     names: Set<string>;
     /** 对称加密服务（SM4） */
-    symmetric: TransportCryptoServiceLike['symmetric'];
+    symmetric: CryptoFunctions['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
@@ -391,19 +246,12 @@ declare function createEncryptedCookieProxy(cookies: Cookies, config: CookieProx
  *
  * @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 },
- * })
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.createHandle({ auth: { verifyToken: async () => null, protectedPaths: ['/admin/**'] } })
+ * void handle
  * ```
  */
 declare function createHandle(config?: HandleConfig): Handle;
@@ -414,81 +262,72 @@ declare function createHandle(config?: HandleConfig): Handle;
  *
  * @param handles - 待组合的 handle 函数列表
  * @returns 组合后的单一 Handle 函数
- *
  * @example
  * ```ts
- * const haiHandle = kit.createHandle({ ... })
- * export const handle = kit.sequence(i18nHandle, haiHandle)
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.sequence(kit.createHandle({ logging: true }), kit.createHandle())
+ * void handle
  * ```
  */
 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
- */
+/** 可直接挂到 SvelteKit catch-all 路由的反馈适配，无 serv 或 Svelte UI 依赖。 */
 
 /**
- * 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[];
-    };
+ * 反馈服务及可信范围解析。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;
 }
 /**
- * 辅助函数：创建端点定义（获得类型推导）
- *
- * @param def - 端点定义对象
- * @returns 同一个对象（类型安全）
+ * 装配反馈 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 defineEndpoint<TInput, TOutput>(def: EndpointDef<TInput, TOutput>): EndpointDef<TInput, TOutput>;
+declare function createFeedbackHandler(options: FeedbackHandlerOptions): RequestHandler;
+
 /**
- * 基于契约创建 API handler
- *
- * - 自动从 request body/query 提取参数
- * - 自动使用契约的 input schema 校验
- * - handler 返回值类型必须匹配 output schema
- * - 自动包装为标准 kit.response.ok() 响应
- *
- * @param endpoint - 端点契约定义
- * @param fn - 业务处理函数（接收校验后的 input 和 RequestEvent）
- * @returns SvelteKit RequestHandler
- *
- * @example
+ * 应用路由直接导出对应 handler；认证 ops 仍由 createHandle 注入。
+ * @param iam - 已由应用初始化的 IAM 服务对象。
+ * @returns 标准认证端点的 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
- * })
+ * function build(iam: IamFunctions) {
+ *   return createAuthApi(iam) // 调用方负责初始化 IAM；工厂只装配 handler。
+ * }
  * ```
  */
-declare function fromContract<TInput, TOutput>(endpoint: EndpointDef<TInput, TOutput>, fn: (input: TInput, event: RequestEvent) => Promise<TOutput>): RequestHandler;
+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;
+};
 
 /**
  * @h-ai/kit — API Handler 包装器
@@ -508,13 +347,12 @@ declare function fromContract<TInput, TOutput>(endpoint: EndpointDef<TInput, TOu
  *
  * @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())
- * })
+ * 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;
@@ -535,10 +373,12 @@ declare function handler(fn: (event: RequestEvent) => Promise<Response> | Respon
  * @param data - 响应数据，序列化为 JSON
  * @param requestId - 可选请求 ID，用于链路追踪
  * @returns `{ success: true, data, requestId }` 格式的 JSON Response
- *
  * @example
  * ```ts
- * return kit.response.ok({ id: '1', name: 'Alice' })
+ * 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;
@@ -548,10 +388,12 @@ declare function ok<T>(data: T, requestId?: string): Response;
  * @param data - 新创建的资源数据
  * @param requestId - 可选请求 ID
  * @returns `{ success: true, data }` 格式的 JSON Response（status 201）
- *
  * @example
  * ```ts
- * return kit.response.created({ id: 'new_1' })
+ * 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;
@@ -561,6 +403,13 @@ declare function created<T>(data: T, requestId?: string): Response;
  * 通常用于 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;
 /**
@@ -572,10 +421,12 @@ declare function noContent(): Response;
  * @param requestId - 可选请求 ID
  * @param details - 可选额外详情
  * @returns `{ success: false, error: { code, message, details } }` 格式的 JSON Response
- *
  * @example
  * ```ts
- * return kit.response.error('QUOTA_EXCEEDED', '配额已用尽', 429)
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.error('ARTICLE_MISSING', 'Article missing', 404)
+ * void response.status
  * ```
  */
 declare function error(code: string, message: string, status?: number, requestId?: string, details?: unknown): Response;
@@ -586,6 +437,13 @@ declare function error(code: string, message: string, status?: number, requestId
  * @param requestId - 可选请求 ID
  * @param details - 可选额外详情
  * @returns error code 为 `'BAD_REQUEST'` 的 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;
 /**
@@ -594,6 +452,13 @@ declare function badRequest(message: string, requestId?: string, details?: unkno
  * @param message - 错误消息，默认 `'Authentication required'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'UNAUTHORIZED'` 的 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;
 /**
@@ -602,6 +467,13 @@ declare function unauthorized(message?: string, requestId?: string): Response;
  * @param message - 错误消息，默认 `'Access denied'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'FORBIDDEN'` 的 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;
 /**
@@ -610,6 +482,13 @@ declare function forbidden(message?: string, requestId?: string): Response;
  * @param message - 错误消息，默认 `'Resource not found'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'NOT_FOUND'` 的 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;
 /**
@@ -618,6 +497,13 @@ declare function notFound(message?: string, requestId?: string): Response;
  * @param message - 冲突描述（如重复创建等）
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'CONFLICT'` 的 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;
 /**
@@ -626,12 +512,12 @@ declare function conflict(message: string, requestId?: string): Response;
  * @param errors - 字段级别的验证错误列表
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'VALIDATION_ERROR'`，details 包含 `errors` 数组
- *
  * @example
  * ```ts
- * return kit.response.validationError([
- *   { field: 'email', message: '格式无效' },
- * ])
+ * 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<{
@@ -644,6 +530,13 @@ declare function validationError(errors: Array<{
  * @param message - 错误消息，默认 `'Internal server error'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'INTERNAL_ERROR'` 的 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;
 /**
@@ -652,10 +545,12 @@ 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)
+ * 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;
@@ -669,14 +564,12 @@ declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Re
  * @param httpStatusMap - 模块导出的错误码 → HTTP 状态码映射表（如 IamErrorHttpStatus）
  * @param requestId - 可选请求 ID，用于链路追踪
  * @returns 标准化 JSON Response
- *
  * @example
  * ```ts
- * // 无映射（默认 400）
- * return kit.response.fromResult(result)
+ * import { kit } from '@h-ai/kit'
  *
- * // 带模块错误码映射
- * return kit.response.fromResult(result, IamErrorHttpStatus)
+ * const response = kit.response.fromResult({ success: true, data: { id: 'article_1' } })
+ * void response.status
  * ```
  */
 declare function fromResult<T>(result: {
@@ -690,15 +583,31 @@ declare function fromResult<T>(result: {
         [key: string]: unknown;
     };
 }, 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` 以走 SvelteKit 控制流）
+ * - 失败抛出：`OrFail`（抛出 `Response`，由 kit.handler 作为 API 控制流处理）
  * @module kit-validation
  */
 
@@ -712,13 +621,12 @@ declare function fromError(haiError: HaiError, requestId?: string): Response;
  * @param schema - Zod Schema
  * @returns 校验通过的数据（类型安全）
  * @throws Response - 400 BadRequest（含首条错误消息）
- *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * export const POST = kit.handler(async ({ request }) => {
- *   const data = await kit.validate.body(request, CreateUserSchema)
- *   // data 类型安全，校验已通过
- * })
+ * 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>>;
@@ -729,10 +637,12 @@ declare function validateFormOrFail<T extends z.ZodType>(request: Request, schem
  * @param schema - Zod Schema
  * @returns 校验通过的数据
  * @throws Response - 400 BadRequest
- *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * const query = kit.validate.query(event.url, PaginationSchema)
+ * 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>;
@@ -743,10 +653,12 @@ declare function validateQueryOrFail<T extends z.ZodType>(url: URL, schema: T):
  * @param schema - Zod Schema
  * @returns 校验通过的数据
  * @throws Response - 400 BadRequest
- *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * const { id } = kit.validate.params(event.params, IdParamSchema)
+ * 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>;
@@ -754,10 +666,12 @@ declare function validateParamsOrFail<T extends z.ZodType>(params: Record<string
  * 路径参数 id 校验 Schema
  *
  * 验证 `event.params.id` 为非空字符串。
- *
  * @example
  * ```ts
- * const { id } = kit.validate.params(event.params, IdParamSchema)
+ * import { IdParamSchema } from '@h-ai/kit'
+ *
+ * const value = IdParamSchema.parse({ id: 'article_1' })
+ * void value
  * ```
  */
 declare const IdParamSchema: z.ZodObject<{
@@ -768,16 +682,12 @@ declare const IdParamSchema: z.ZodObject<{
  *
  * 包含 page（默认 1）、pageSize（默认 20，上限 100）、search（可选）。
  * 可通过 `.extend()` 扩展业务字段。
- *
  * @example
  * ```ts
- * // 直接使用
- * const { page, pageSize, search } = kit.validate.query(url, PaginationQuerySchema)
+ * import { PaginationQuerySchema } from '@h-ai/kit'
  *
- * // 扩展业务字段
- * const ListUsersSchema = PaginationQuerySchema.extend({
- *   enabled: z.enum(['true', 'false']).transform(v => v === 'true').optional(),
- * })
+ * const value = PaginationQuerySchema.parse({ page: '1', pageSize: '20' })
+ * void value
  * ```
  */
 declare const PaginationQuerySchema: z.ZodObject<{
@@ -790,18 +700,33 @@ declare const PaginationQuerySchema: z.ZodObject<{
  * Kit 模块统一出口。
  *
  * 作为纯工具模块，kit 不需要 init/close 生命周期，
- * 所有功能均为无状态工厂函数或工具函数。
+ * 依赖服务、请求上下文和创建后句柄的状态由调用方按各自契约管理。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.createHandle({ logging: true })
+ * void handle
+ * ```
  */
 declare const kit: {
+    /** 创建反馈的受控 catch-all HTTP handler，身份范围由宿主解析。 */
+    createFeedbackHandler: typeof createFeedbackHandler;
+    /** 原子限流工厂；共享store生命周期由应用管理。 */
+    middleware: {
+        rateLimit: typeof rateLimitMiddleware;
+        createCacheRateLimitStore: typeof createCacheRateLimitStore;
+        createMemoryRateLimitStore: typeof createMemoryRateLimitStore;
+    };
     /** 创建 SvelteKit Handle Hook（含 auth / logging / rateLimit 内置配置） */
     createHandle: typeof createHandle;
     /** 组合多个 Handle */
     sequence: typeof sequence;
     /** API Handler 包装器（自动错误边界） */
     handler: typeof handler;
-    /** 基于 API 契约创建类型安全的路由 handler */
-    fromContract: typeof fromContract;
     guard: {
+        /** 选定敏感操作要求单次再鉴别；先调用现有权限与资源守卫。 */
+        requireSensitive: typeof requireSensitiveOperation;
         /** 要求权限，不满足时 throw Response（SvelteKit 控制流） */
         require: typeof requirePermission;
         /** 检查会话是否具有指定权限（布尔） */
@@ -858,8 +783,21 @@ declare const kit: {
     client: {
         /** 创建统一客户端（CSRF + 传输加密透明合并） */
         create: typeof createKitClient;
+        /** 标准认证表单动作（Cookie 模式）。 */
+        createAuthActions: typeof createKitAuthActions;
+        /**
+         * 用解析后的 {@link KitConfig} 一键安装浏览器端传输加密
+         * （应用层推荐入口；内部预热 crypto 并调用 installBrowserTransportFetch）
+         */
+        installBrowserTransport: typeof installBrowserTransport;
+        /** 底层入口：直接传 transport 配置安装浏览器全局 fetch 包装 */
+        installBrowserTransportFetch: typeof installBrowserTransportFetch;
     };
     auth: {
+        /** 标准匿名认证端点白名单。 */
+        publicPaths: string[];
+        /** 标准配置/登录/注册/验证码/重置 handler 集合。 */
+        createApi: typeof createAuthApi;
         /** 服务端登录（密码）：内部调用 iam.auth.login + 自动写入 Token Cookie */
         login: typeof login;
         /** 服务端登录（OTP 验证码）：内部调用 iam.auth.loginWithOtp + 自动写入 Token Cookie */
@@ -876,10 +814,6 @@ declare const kit: {
         setBrowserToken: typeof setBrowserToken;
         /** 清除浏览器端 Access Token（客户端 logout 用） */
         clearBrowserToken: typeof clearBrowserToken;
-        /** 创建浏览器端 Token 存储器（自定义 key 时使用） */
-        createTokenStore: typeof createTokenStore;
-        /** 创建浏览器端同源请求自动附加 Authorization 的 HandleFetch */
-        createHandleFetch: typeof createHandleFetch;
     };
     crud: {
         /** 定义 CRUD 资源（声明式配置 → 操作对象） */
@@ -888,38 +822,11 @@ declare const kit: {
     i18n: {
         /** 统一设置所有 hai 模块的默认语言 */
         setLocale: typeof setAllModulesLocale;
+        /** 请求/SSR 语言隔离；异步处理使用同一请求上下文。 */
+        runWithLocale: <T>(locale: _h_ai_core.Locale, operation: () => T) => T;
     };
 };
 
-/**
- * @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 — 日志中间件
  *
@@ -930,34 +837,21 @@ declare function corsMiddleware(config?: CorsConfig): Middleware;
 
 /**
  * 日志中间件配置
+ * @example
+ * ```ts
+ * import type { LoggingMiddlewareConfig } from '@h-ai/kit'
+ *
+ * const value: LoggingMiddlewareConfig = { logBody: false }
+ * void value
+ * ```
  */
 interface LoggingMiddlewareConfig {
     /** 为 `true` 时记录非 GET 请求体（自动脱敏） */
     logBody?: boolean;
     /** 为 `true` 时记录响应头 */
     logResponse?: boolean;
-    /** 指定需要脱敏的字段名（默认 `['password', 'token', 'secret']`） */
+    /** 查询参数和 JSON 正文的脱敏字段；默认包含 password/token/secret、授权/API Key 和银行卡字段。 */
     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 };
+export { type AuthGuardConfig, type CookieProxyConfig, type FeedbackHandlerOptions, HandleConfig, IdParamSchema, type LoggingMiddlewareConfig, PaginationQuerySchema, type PermissionGuardConfig, type RoleGuardConfig, SessionData, type SessionGuardConfig, SessionLike, defineCrud, kit, matchPermission };