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

package/dist/{kit-types-ByWdbCeO.d.ts → kit-types-CnzhN-AS.d.ts}

@@ -1,11 +1,12 @@
-import { CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
+import { CryptoFunctions, TransportServerKeyRing, TransportKeyStore } from '@h-ai/crypto';
 import { AuthnOperations } from '@h-ai/iam';
 import { RequestEvent } from '@sveltejs/kit';
+import { HaiResult } from '@h-ai/core';
 
 /**
  * @h-ai/kit — 速率限制中间件
  *
- * 基于滑动窗口的请求速率限制中间件。
+ * 以首个成功请求为起点的固定窗口限流；后续计数不延长窗口。
  * 内置内存存储（`MemoryRateLimitStore`），并支持通过 `RateLimitStore` 接入
  * Redis 等外部存储后端。
  * @module kit-ratelimit
@@ -13,6 +14,13 @@ import { RequestEvent } from '@sveltejs/kit';
 
 /**
  * 速率限制存储条目
+ * @example
+ * ```ts
+ * import type { RateLimitEntry } from '@h-ai/kit'
+ *
+ * const value: RateLimitEntry = { count: 1, resetAt: Date.now() + 60_000 }
+ * void value
+ * ```
  */
 interface RateLimitEntry {
     /** 当前窗口内的请求次数 */
@@ -21,92 +29,135 @@ interface RateLimitEntry {
     resetAt: number;
 }
 /**
- * 速率限制存储接口
- *
- * 内置 `MemoryRateLimitStore` 适合单进程开发；
- * 多实例部署需传入基于 Redis / @h-ai/cache 的分布式实现。
- *
+ * 原子固定窗口计数器；故障抛错由中间件转为503，禁止读改写回退。
  * @example
  * ```ts
- * // 自定义 Redis 存储
- * const redisStore: RateLimitStore = {
- *   async get(key) { ... },
- *   async set(key, entry) { ... },
- *   async delete(key) { ... },
+ * import type { RateLimitStore } from '@h-ai/kit'
+ *
+ * async function count(store: RateLimitStore) {
+ *   return store.increment('client_1', 60_000)
  * }
- * kit.middleware.rateLimit({ windowMs: 60_000, maxRequests: 100, store: redisStore })
  * ```
  */
 interface RateLimitStore {
-    /** 获取指定 key 的限流条目 */
-    get: (key: string) => Promise<RateLimitEntry | undefined> | RateLimitEntry | undefined;
-    /** 设置限流条目 */
-    set: (key: string, entry: RateLimitEntry) => Promise<void> | void;
-    /** 删除指定 key 的限流条目 */
-    delete: (key: string) => Promise<void> | void;
-    /**
-     * 原子自增并返回当前计数和重置时间
-     *
-     * 实现时必须保证 get→increment→set 操作的原子性，
-     * 防止并发请求在窗口切换时产生竞态绕过限流。
-     * 若未实现，则退回非原子 get+set 流程。
-     *
-     * @param key - 限流键
-     * @param windowMs - 窗口时长（ms）
-     * @returns 自增后的计数和窗口重置时间
-     */
-    increment?: (key: string, windowMs: number) => Promise<RateLimitEntry> | RateLimitEntry;
+    /** 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>>;
+    };
+}
+/**
+ * 创建共享缓存固定窗口计数器；Redis/Cluster的CAS与TTL构成原子边界。
+ * 只有缓存键实际过期才新建窗口，节点时钟只影响响应头估算，不提前重置计数。
+ * @param backend - 已初始化的cache模块；每次请求重新核对provider，防止切换后回退内存
+ * @param options - 业务限流命名空间与显式开发内存选项
+ * @param options.namespace - 同一策略的稳定业务范围
+ * @param options.allowMemory - 仅开发或显式HAI_E2E测试允许内存cache
+ * @returns 无内部定时器、不接管cache生命周期的计数器；基础设施错误显式抛错
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * import { cache } from '@h-ai/cache'
+ *
+ * // 应用在启动时先初始化 Redis cache，关闭时由应用统一回收。
+ * const store = kit.middleware.createCacheRateLimitStore(cache, { namespace: 'api' })
+ * void store
+ * ```
+ */
+declare function createCacheRateLimitStore(backend: RateLimitCache, options: {
+    namespace: string;
+    allowMemory?: boolean;
+}): RateLimitStore;
+/**
+ * 创建显式开发/测试计数器；无定时器，最多保存 10000 个窗口，生产拒绝内存模式。
+ * @returns 由调用者持有的计数器；丢弃引用即可回收，无需关闭，也不接管外部 store。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * // 开发/测试进程；生产环境会明确拒绝内存计数。
+ * const store = kit.middleware.createMemoryRateLimitStore()
+ * const entry = await store.increment('client_1', 60_000)
+ * void entry.count
+ * ```
+ */
+declare function createMemoryRateLimitStore(): MemoryRateLimitStore;
 /**
  * 内存速率限制存储
  *
- * 基于 Map 实现，适合单进程/开发环境。
- * 多实例部署时限流上限会乘以实例数，建议使用分布式 Store。
+ * 基于 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 cleanupTimer;
+    private cleanupCursor;
     /**
-     * 启动定期清理过期条目
-     *
-     * @param intervalMs - 清理间隔（毫秒）
-     */
-    startCleanup(intervalMs: number): void;
-    /**
-     * 停止定期清理并释放定时器资源
-     *
-     * 调用后可再次 startCleanup 重启。进程退出 / 热重载 / 测试拆装场景必须调用以
-     * 避免资源泄漏。
+     * 有界惰性回收；保留迭代位置，避免每次从头扫描使尾部过期项永久滞留。
+     * @param now - 当前请求时间，等于 resetAt 时窗口已经失效。
      */
-    stopCleanup(): void;
-    get(key: string): RateLimitEntry | undefined;
-    set(key: string, entry: RateLimitEntry): void;
-    delete(key: string): void;
+    private prune;
     /**
      * 原子自增（内存实现为同步操作，天然原子）
      *
      * @param key - 限流键
      * @param windowMs - 窗口时长
-     * @returns 自增后的条目
+     * @returns 自增后的快照，修改返回对象不会改变已保存的计数。
+     * @throws 新 key 超出容量或期限非法；中间件将其转换为 503。
+     * @example store.increment('client', 60_000)
      */
     increment(key: string, windowMs: number): RateLimitEntry;
 }
 /**
  * 创建速率限制中间件
  *
- * 基于可插拔存储的滑动窗口限流：
+ * 基于必选原子存储的固定窗口限流：
  * - 超限时返回 429，并在响应头中告知重置时间
  * - 正常响应附带 `X-RateLimit-*` 头
- * - 默认使用内存存储（单进程），可传入 `store` 实现分布式限流
+ * - 必须显式传入 store；生产使用共享计数器，故障返回503
  *
  * @param config - 限流配置
  * @returns Middleware 实例
- *
  * @example
  * ```ts
- * middleware: [
- *   kit.middleware.rateLimit({ windowMs: 60_000, maxRequests: 100 }),
- * ]
+ * import { kit } from '@h-ai/kit'
+ *
+ * import { cache } from '@h-ai/cache'
+ *
+ * // Redis 由应用初始化和关闭；多节点复用相同 namespace。
+ * const middleware = kit.middleware.rateLimit({ windowMs: 60_000, maxRequests: 100, store: kit.middleware.createCacheRateLimitStore(cache, { namespace: 'api' }) })
+ * void middleware
  * ```
  */
 declare function rateLimitMiddleware(config: RateLimitConfig): Middleware;
@@ -123,9 +174,28 @@ declare function rateLimitMiddleware(config: RateLimitConfig): Middleware;
  *
  * 注入后，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);
 /**
  * 会话数据最小接口
@@ -133,6 +203,13 @@ 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 */
@@ -152,18 +229,12 @@ interface SessionLike {
  *
  * 应用层可通过 `& { displayName: string }` 等方式扩展，
  * 扩展后的类型自动兼容所有守卫和权限检查函数（它们接受 `SessionLike`）。
- *
  * @example
  * ```ts
- * const session: SessionData = {
- *   userId: 'u_123',
- *   username: 'alice',
- *   roles: ['admin'],
- *   permissions: ['user:read', 'user:write'],
- * }
+ * import type { SessionData } from '@h-ai/kit'
  *
- * // 应用层扩展
- * type AppSession = SessionData & { displayName: string, avatarUrl: string }
+ * const value: SessionData = { userId: 'user_1', username: 'alice', roles: ['editor'], permissions: ['article:read'] }
+ * void value
  * ```
  */
 interface SessionData {
@@ -184,6 +255,14 @@ interface SessionData {
  * 扩展的请求事件
  *
  * 在 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 {
     /** 会话数据 */
@@ -196,6 +275,14 @@ interface HaiRequestEvent extends RequestEvent {
  *
  * 由 `createHandle` 构建，传递给所有中间件函数。
  * 包含当前请求事件、已解析的会话以及请求唯一 ID。
+ * @example
+ * ```ts
+ * import type { MiddlewareContext } from '@h-ai/kit'
+ *
+ * function requestLabel(context: MiddlewareContext) {
+ *   return context.event.url.pathname + ':' + context.requestId
+ * }
+ * ```
  */
 interface MiddlewareContext {
     /** 请求事件 */
@@ -209,15 +296,12 @@ interface MiddlewareContext {
  * 中间件函数
  *
  * 遵循洋葱模型：调用 `next()` 前执行前置逻辑，调用后执行后置逻辑。
- *
  * @example
  * ```ts
- * const timing: Middleware = async (ctx, next) => {
- *   const start = Date.now()
- *   const response = await next()
- *   response.headers.set('X-Duration', `${Date.now() - start}ms`)
- *   return response
- * }
+ * 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>;
@@ -226,6 +310,13 @@ type Middleware = (context: MiddlewareContext, next: () => 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 {
     /** 是否允许访问 */
@@ -241,13 +332,12 @@ interface GuardResult {
  * 路由守卫函数
  *
  * 接收请求事件与可选会话，返回 `GuardResult`（同步或异步均可）。
- *
  * @example
  * ```ts
- * const myGuard: RouteGuard = (event, session) => {
- *   if (!session) return { allowed: false, status: 401 }
- *   return { allowed: true }
- * }
+ * 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;
@@ -256,14 +346,12 @@ type RouteGuard = (event: RequestEvent, session?: SessionData) => Promise<GuardR
  *
  * 在 `createHandle({ guards })` 中使用。
  * `paths` 支持 `/*` 和 `/**` 通配符，`exclude` 优先于 `paths`。
- *
  * @example
  * ```ts
- * const config: GuardConfig = {
- *   guard: kit.guard.auth({ apiMode: true }),
- *   paths: ['/api/*'],
- *   exclude: ['/api/health'],
- * }
+ * import type { GuardConfig } from '@h-ai/kit'
+ *
+ * const value: GuardConfig = { paths: ['/admin/**'], guard: (_event, session) => ({ allowed: Boolean(session) }) }
+ * void value
  * ```
  */
 interface GuardConfig {
@@ -284,17 +372,12 @@ interface GuardConfig {
  *
  * API 路径（以 `/api/` 开头）未认证时返回 401 JSON；
  * 非 API 路径未认证时重定向到 `loginUrl`（若配置）或返回 401。
- *
  * @example
  * ```ts
- * kit.createHandle({
- *   auth: {
- *     verifyToken: validateSession,
- *     loginUrl: '/auth/login',
- *     protectedPaths: ['/admin/*', '/api/*'],
- *     publicPaths: ['/api/auth/*', '/api/public/*'],
- *   },
- * })
+ * import type { HandleAuthConfig } from '@h-ai/kit'
+ *
+ * const value: HandleAuthConfig = { verifyToken: async () => null, protectedPaths: ['/admin/**'], loginUrl: '/auth/login' }
+ * void value
  * ```
  */
 interface HandleAuthConfig {
@@ -327,19 +410,12 @@ interface HandleAuthConfig {
  * 3. 执行路由守卫
  * 4. 执行中间件链（logging / rateLimit / 自定义）
  * 5. 调用 resolve + 附加 `X-Request-Id` 响应头
- *
  * @example
  * ```ts
- * kit.createHandle({
- *   auth: {
- *     verifyToken: validateSession,
- *     loginUrl: '/auth/login',
- *     protectedPaths: ['/admin/*', '/api/*'],
- *     publicPaths: ['/api/auth/*'],
- *   },
- *   rateLimit: { maxRequests: 100 },
- *   crypto: { crypto, transport: true },
- * })
+ * import type { HandleConfig } from '@h-ai/kit'
+ *
+ * const value: HandleConfig = { logging: true, auth: { verifyToken: async () => null, protectedPaths: ['/admin/**'] } }
+ * void value
  * ```
  */
 interface HandleConfig {
@@ -356,7 +432,7 @@ interface HandleConfig {
      * 提供对象启用速率限制；设为 `false` 显式禁用。
      * 不提供则不开启速率限制。
      */
-    rateLimit?: {
+    rateLimit?: Omit<RateLimitConfig, 'windowMs' | 'maxRequests'> & {
         windowMs?: number;
         maxRequests?: number;
     } | false;
@@ -398,6 +474,13 @@ interface HandleConfig {
  * 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 对象） */
@@ -415,16 +498,12 @@ interface HandleA2AOperations {
 }
 /**
  * A2A Handle 配置（高级模式）
- *
  * @example
  * ```ts
- * kit.createHandle({
- *   a2a: {
- *     operations: ai.a2a,
- *     rpcPath: '/api/a2a',
- *     authenticate: 'apiKey', // 自动使用 IAM API Key 验证
- *   },
- * })
+ * 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 {
@@ -445,41 +524,36 @@ interface HandleA2AConfig {
 }
 /**
  * 传输加密详细配置
+ * @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 {
+    /** 受管服务端版本化密钥环，不进入公开 YAML/客户端配置。 */
+    serverKeyRing: TransportServerKeyRing;
     /** 密钥交换端点路径（默认 `'/api/_hai/key-exchange'`） */
     keyExchangePath?: string;
     /** 排除路径（不加密），支持精确匹配和前缀匹配 */
     excludePaths?: string[];
-    /**
-     * 是否强制要求传输加密（默认 `true`）
-     *
-     * - `true`：非排除路径上缺少 X-Client-Id 请求头时返回 400
-     * - `false`：缺少 X-Client-Id 时透传明文（仅用于渐进式迁移，不建议生产启用）
-     */
-    requireEncryption?: boolean;
-    /** 是否加密响应体（默认 `true`） */
-    encryptResponse?: boolean;
-    /** 服务端可缓存的客户端公钥数量上限（默认 `10000`） */
-    maxClients?: number;
     /** 共享客户端公钥存储；适用于多节点部署。 */
-    keyStore?: TransportKeyStore;
+    keyStore: TransportKeyStore;
 }
 /**
  * Handle Hook 加密配置
  *
  * 在 `kit.createHandle({ crypto: { ... } })` 中使用。
- *
  * @example
  * ```ts
- * kit.createHandle({
- *   crypto: {
- *     crypto: cryptoInstance,
- *     transport: true,
- *     encryptedCookies: ['hai_session'],
- *     cookieEncryptionKey: process.env.HAI_KIT_COOKIE_KEY,
- *   },
- * })
+ * import type { HookCryptoConfig, TransportEncryptionOptions } from '@h-ai/kit'
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function config(transport: TransportEncryptionOptions): HookCryptoConfig { return { crypto, transport } }
  * ```
  */
 interface HookCryptoConfig {
@@ -487,10 +561,10 @@ interface HookCryptoConfig {
     crypto: CryptoFunctions;
     /**
      * 启用传输加密。
-     * - `true`：使用默认配置
-     * - 对象：自定义配置
+     * - `false` 或省略：关闭
+     * - 对象：必填受管 serverKeyRing / keyStore，可附加公开路径配置
      */
-    transport?: boolean | TransportEncryptionOptions;
+    transport?: false | TransportEncryptionOptions;
     /**
      * 需要加密的 Cookie 名称列表
      *
@@ -511,13 +585,12 @@ interface HookCryptoConfig {
  *
  * `kit.response.*` 系列函数统一返回此结构的 JSON 响应。
  * 成功时 `success: true` 且 `data` 有值；失败时 `success: false` 且 `error` 有值。
- *
  * @example
  * ```ts
- * // 成功
- * { success: true, data: { id: '1' }, requestId: 'req_abc' }
- * // 失败
- * { success: false, error: { code: 'NOT_FOUND', message: 'Resource not found' } }
+ * import type { ApiResponse } from '@h-ai/kit'
+ *
+ * const value: ApiResponse<{ id: string }> = { success: true, data: { id: 'article_1' } }
+ * void value
  * ```
  */
 interface ApiResponse<T = unknown> {
@@ -539,6 +612,13 @@ interface ApiResponse<T = unknown> {
  *
  * 由 `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 {
     /** 字段名 */
@@ -550,12 +630,12 @@ interface FormError {
  * 表单验证结果
  *
  * @template T - Zod schema 推导出的数据类型
- *
  * @example
  * ```ts
- * const { valid, data, errors } = await kit.validate.form(request, schema)
- * if (!valid) return kit.response.validationError(errors)
- * // data 此时类型安全
+ * import type { FormValidationResult } from '@h-ai/kit'
+ *
+ * const value: FormValidationResult<{ title: string }> = { valid: true, data: { title: 'Example' }, errors: [] }
+ * void value
  * ```
  */
 interface FormValidationResult<T> {
@@ -569,15 +649,16 @@ interface FormValidationResult<T> {
 /**
  * 速率限制配置
  *
- * 基于可插拔存储的滑动窗口限流。超限后返回 429 状态码与 `Retry-After` 响应头。
- * 默认使用内存存储（单进程），多实例部署请传入分布式 `store` 实现。
- *
+ * 基于可插拔原子存储的固定窗口限流。超限后返回 429 状态码与 `Retry-After` 响应头。
+ * 必须显式传入 store；生产使用共享计数器，故障返回503。
  * @example
  * ```ts
- * kit.middleware.rateLimit({
- *   windowMs: 60_000,   // 1 分钟
- *   maxRequests: 100,   // 最多 100 次
- * })
+ * 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 {
@@ -592,23 +673,20 @@ interface RateLimitConfig {
     /**
      * 自定义存储实现
      *
-     * 默认使用 `MemoryRateLimitStore`（单进程）。
-     * 多实例部署时传入基于 Redis / @h-ai/cache 的分布式 Store。
+     * 必须提供原子 increment；不支持 get+set 回退。共享缓存由调用方初始化和关闭。
      */
-    store?: RateLimitStore;
+    store: RateLimitStore;
 }
 /**
  * CORS 中间件配置
  *
  * 配置跨域资源共享策略。预检请求（OPTIONS）自动返回 204。
- *
  * @example
  * ```ts
- * kit.middleware.cors({
- *   origin: ['https://example.com'],
- *   credentials: true,
- *   maxAge: 86400,
- * })
+ * import type { CorsConfig } from '@h-ai/kit'
+ *
+ * const value: CorsConfig = { origin: ['https://app.example.com'], credentials: true }
+ * void value
  * ```
  */
 interface CorsConfig {
@@ -628,4 +706,4 @@ interface CorsConfig {
     capacitor?: boolean;
 }
 
-export { type ApiResponse as A, type CorsConfig as C, type FormError as F, type GuardConfig as G, type HaiRequestEvent as H, type Middleware as M, type RateLimitConfig as R, type SessionData as S, type TransportEncryptionOptions as T, type AuthOperations as a, type AuthOperationsProvider as b, type FormValidationResult as c, type GuardResult as d, type HandleA2AConfig as e, type HandleA2AOperations as f, type HandleAuthConfig as g, type HandleConfig as h, type HookCryptoConfig as i, type MiddlewareContext as j, type RouteGuard as k, type SessionLike as l, MemoryRateLimitStore as m, type RateLimitEntry as n, type RateLimitStore as o, rateLimitMiddleware as r };
+export { type ApiResponse as A, type CorsConfig as C, type FormError as F, type GuardConfig as G, type HaiRequestEvent as H, type Middleware as M, type RateLimitConfig as R, type SessionData as S, type TransportEncryptionOptions as T, type AuthOperations as a, type AuthOperationsProvider as b, type FormValidationResult as c, type GuardResult as d, type HandleA2AConfig as e, type HandleA2AOperations as f, type HandleAuthConfig as g, type HandleConfig as h, type HookCryptoConfig as i, type MiddlewareContext as j, type RouteGuard as k, type SessionLike as l, createCacheRateLimitStore as m, createMemoryRateLimitStore as n, MemoryRateLimitStore as o, type RateLimitCache as p, type RateLimitEntry as q, rateLimitMiddleware as r, type RateLimitStore as s };