@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

package/templates/skills/hai-kit/SKILL.md

@@ -1,354 +1,58 @@
 ---
 name: hai-kit
-description: 使用 @h-ai/kit 构建 SvelteKit 请求管道与 API 安全边界（handle/guard/middleware/handler/validate/response/fromContract）。当需求涉及 hooks.server.ts、权限守卫、限流、统一响应、Bearer Token 认证、契约处理或 CORS 配置时使用。
+description: "在 SvelteKit 中接入 hooks、认证守卫、输入校验、响应和同源加密客户端；不用于独立 serv 服务。"
 ---
 
 # hai-kit
 
-`@h-ai/kit` 是 hai-framework 的 SvelteKit 集成层。它把请求处理中的"通用横切能力"收敛到统一命名空间 `kit`：
+限流采用首次成功提交为起点的固定窗口，后续请求不延长 TTL。必须显式传 store；应用先检查共享 Redis 初始化结果，所有节点使用相同 namespace/windowMs/maxRequests。缓存读取/条件提交失败或冲突耗尽返回503，超限429；不会回退 get+set 或本地计数。createMemoryRateLimitStore 仅开发或显式 HAI_E2E/HAI_E2E_MOCK 测试使用，无常驻定时器，丢弃引用即可回收；每次请求最多惰性扫描 64 项，最多保存 10000 个窗口，容量满时对新 key 返回503且不驱逐有效计数，外部 store 生命周期由创建者管理；生产不得设置测试开关。响应重置时间为节点时钟估算，实际窗口由 Redis TTL 决定，须同步时钟。默认键只读取可信 adapter 的 getClientAddress、规范化等价IPv6和IPv4映射地址，不采信原始转发头；代理信任通过部署adapter配置。
 
-- 请求入口：`createHandle` / `sequence`
-- 安全边界：`guard` / `middleware`
-- API 工具：`handler` / `response` / `validate`
-- Bearer Token 认证：从 `Authorization` header 解析，SSR 端通过 `hai_token` Cookie 透传
-- 契约处理：`fromContract(endpoint, fn)` — 基于 EndpointDef 的类型安全 handler
-- 双构建模式：`createAdapter()` 根据环境变量选择 adapter-node 或 adapter-static
+transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、5 分钟窗口、nonce 持久化与实现示例见 [参考](reference.md)。
 
-## 模块概述
+## 能力契约
 
-当任务涉及以下关键词时，优先使用本 Skill：
+| 项目     | 契约                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------- |
+| 能力     | 使用 @h-ai/kit 集成 SvelteKit hooks、守卫、校验、响应及同源客户端传输                                   |
+| 适用场景 | SvelteKit hooks、load 和同源端点集成                                                                    |
+| 输入     | SvelteKit handle/RequestEvent、schema、guard、transport                                                 |
+| 输出     | handle、Response、校验值和客户端请求结果                                                                |
+| 限制     | 无 init/close；保留 SvelteKit 控制流异常。跨端共享 HTTP contract 用 api-contract + serv，勿复制到 kit。 |
 
-- `hooks.server.ts`
-- `kit.createHandle` / `kit.sequence`
-- `kit.guard.*`（`require` / `check`）
-- `kit.handler` / `kit.response` / `kit.validate`
-- `kit.fromContract(endpoint, fn)` — 契约到 SvelteKit handler
-- `kit.client.create()` — 浏览器端统一 API 客户端（`apiFetch`）
-- `kit.auth.createTokenStore()` — 浏览器端 Token 存储
-- `kit.auth.createHandleFetch()` — `hooks.client.ts` 自动附加 Token
-- Bearer Token / `Authorization` header
-- CORS 配置（含 Capacitor Origin 预设）
-- 传输加密（key exchange / `X-Client-Id`）
+容量通过 resolveTransportBodyLimits(explicitLimit, { requiredPlaintextBytes }) 合并：省略/auto 才按模块需求推导，显式整数不足时报错，不得静默取大或覆盖。Serv/Kit auto 解析为 undefined；部署代理和 BODY_SIZE_LIMIT 与运行时复用同一结果，反馈业务预算独立。
 
-> **重要变更**：Cookie Session 和 CSRF 中间件已移除。统一使用 Bearer Token 认证。
+## 使用路径
 
-## 依赖
+1. 仅在 SvelteKit 集成；先查现有 hooks、配置、守卫与路由，不将其套用于独立 serv 应用。
+2. 用 createHandle 编排已初始化模块；认证 API 与公开路径复用 kit.auth，客户端复用框架动作。
+3. 区分返回 HaiResult 的业务操作与抛 Response/redirect/error 的框架控制流，不吞掉控制流。
+4. 对齐 Cookie/CSRF/transport 与服务端配置，验证匿名、登录、权限拒绝和表单失败。
 
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/iam` | 身份认证与授权（A2A 认证） | 可选 | 使用 A2A 功能时需在 kit 使用前初始化 |
-| `@h-ai/crypto` | 加密（传输加密 / Cookie 加密） | 可选 | 启用加密时需在 kit 使用前初始化 |
+默认请求日志支持 prerender：查询应从独立 `new URL(event.request.url)` 读取，路径保留 `event.url.pathname`，不为观测读取跟踪 URL 的 search/searchParams 而建立页面依赖或触发静态构建错误。保持默认日志开启、JSON 正文日志默认关闭；查询/可选正文先脱敏再写 trace，正文读取副本，不能消耗业务请求。页面业务确实依赖查询时仍按 SvelteKit 的动态路由条件处理，不用日志绕过来声明业务可静态生成。
 
-## 使用步骤
+Kit 自动请求审计与 Serv 一样，仅在请求时发现 audit.isInitialized 才写入；未选 Audit 的站点不因默认 handle 产生未初始化错误。选择 Audit 时检查 init 结果并失败停止启动；显式业务审计仍遵守初始化和事务合同，已就绪模块写入失败必须保留诊断，不能当作可选模块静默跳过。handle 创建早于模块初始化时不能在装配阶段把审计永久禁用。
 
-### 1) 在 `hooks.server.ts` 搭建请求管道
+服务端 transport 使用含受管 serverKeyRing、共享 keyStore 的对象，不再接受单独 true。公开 _kit.yml 只保留路径/开关，不放私钥；浏览器无 ring。请求携带协商 serverKeyId，各节点同 ring + registry，不依赖粘性路由；轮换见 hai-crypto。
 
-```typescript
-import { kit } from '@h-ai/kit'
+传输加密按实际请求/响应 body 判断空正文，不信任 Content-Type/Length；非空明文不能借缺头、chunked 或伪造零长度旁路，实际空流保留无 input POST 行为。
 
-export const handle = kit.createHandle({
-  auth: {
-    verifyToken: async token => token
-      ? { userId: 'u_1', roles: ['admin'], permissions: ['user:read'] }
-      : null,
-    loginUrl: '/auth/login',
-    protectedPaths: ['/admin/*', '/api/*'],
-    publicPaths: ['/api/auth/*', '/api/public/*'],
-  },
-  rateLimit: { windowMs: 60_000, maxRequests: 100 },
-  logging: true,
-  cors: {
-    origins: ['https://example.com'],
-    capacitor: true, // 自动添加 capacitor://localhost 等原生 App Origin
-  },
-})
-```
+业务容量统一配置 transport.maxPlaintextBytes：UTF-8 JSON 明文字节，默认 1 MiB，有效整数范围 1 KiB～64 MiB，请求和响应共用。客户端从握手获取服务端预算，可选本地上限取较小值；resolveTransportBodyLimits 自动推导密文预算为两倍明文加 32 KiB。握手 JSON 16 KiB、公钥 4 KiB、认证头 16 KiB、路径 8 KiB、认证及防重放保持独立。原流超限/取消立即停止、取消并释放 reader；请求 413、响应返回加密的 500 容量错误，客户端识别 TransportBodyTooLargeError / hai:crypto:070。 通过 _kit.yml 的 transport.maxPlaintextBytes 或对应 HAI_*_TRANSPORT_MAXPLAINTEXTBYTES 配置并转发到服务端 transport；重建正文保留 signal 并删除旧长度/编码头。
 
-### 2) API 端点使用 `kit.handler`
+错误提示与诊断分离：HTTP/UI 边界用 core.error.toPublic，仅公开 i18n 安全消息及 error.traceId；重新翻译后用 core.error.formatMessage 保留关联。ToastContainer 默认只显示可读说明，自动将编号移入排查信息图标，展开后可查看、复制并提供给客户支持或开发人员。前后端日志传完整 Error 和操作上下文，使用同一 requestId/traceId 并脱敏；禁止只写通用错误标题，也不能把 cause/ext/SQL/绑定值直接返回用户。数据库日志保留安全的驱动错误码、消息和堆栈。
 
-```typescript
-import { kit } from '@h-ai/kit'
-import { z } from 'zod'
+## 按需参考
 
-const CreateSchema = z.object({ name: z.string().min(1) })
+按路径/IP/时间检查每次请求、真实 IP 与独立文件见[请求访问控制](../hai-core/request-access.md)。完整 Kit 配置只在服务端读取，浏览器接收 transport 等公开投影。
 
-export const POST = kit.handler(async ({ request, locals }) => {
-  kit.guard.require(locals.session, 'user:create')
-  const data = await kit.validate.body(request, CreateSchema)
-  return kit.response.created(data)
-})
-```
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-### 3) 基于契约的类型安全 handler（推荐）
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [常见模式](reference.md#常见模式)
+- [声明式 CRUD 表单字段](reference.md#声明式-crud-表单字段)
 
-```typescript
-import { iam } from '@h-ai/iam'
-import { iamEndpoints } from '@h-ai/iam/api'
-import { kit } from '@h-ai/kit'
+Node 请求/SSR 必须用 `core.i18n.runWithLocale(locale, callback)`（kit 同名方法）包裹实际异步 resolve；serv 自动建立请求语言上下文。浏览器 setGlobalLocale/createLocaleStore 继续管理应用语言，SSR 的 UI setter/store 不写全局值。显式 MessageOptions.locale 优先；进程默认语言仅在启动时设置。
 
-// 入参自动 Zod 校验，返回值类型安全
-export const POST = kit.fromContract(iamEndpoints.login, async (input, event) => {
-  const result = await iam.auth.login(input)
-  if (!result.success) {
-    return kit.response.unauthorized(result.error.message)
-  }
-  return kit.response.ok(result.data)
-})
-```
+认证 Cookie 在 NODE_ENV 或 HAI_CORE_ENV 为 production 时默认启用 Secure，HAI_E2E/HAI_E2E_MOCK 不降低 Cookie 安全；限流生产判断也识别这两个环境标志，测试开关仅放宽共享状态要求。
 
-### 4) CORS 配置
-
-```typescript
-export const handle = kit.createHandle({
-  cors: {
-    origins: ['https://example.com', 'https://*.example.com'], // 支持通配符
-    capacitor: true, // 自动添加 capacitor://localhost, ionic://localhost 等
-    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
-    credentials: true,
-  },
-})
-```
-
-### 5) 需要传输加密时启用 `crypto` 配置
-
-```typescript
-import { crypto } from '@h-ai/crypto'
-import { kit } from '@h-ai/kit'
-
-export const handle = kit.createHandle({
-  crypto: {
-    crypto,
-    transport: true,
-    cookieEncryptionKey: process.env.HAI_KIT_COOKIE_KEY,
-  },
-})
-```
-
-## 核心 API
-
-| API                         | 用途                   | 关键点                                        |
-| --------------------------- | ---------------------- | --------------------------------------------- |
-| `kit.createHandle(config?)` | 创建 SvelteKit Handle  | Bearer Token 解析、守卫、中间件、CORS         |
-| `kit.sequence(...handles)`  | 组合多个 Handle        | 洋葱模型顺序执行                              |
-| `kit.handler(fn)`           | 包装 API 处理函数      | 非控制流异常统一转 500                        |
-| `kit.fromContract(ep, fn)`  | 契约到 handler         | 自动 Zod 入参校验，类型安全                   |
-| `kit.guard.*`               | 权限守卫               | `require`（throw 式） / `check`（布尔）       |
-| `kit.response.*`            | 标准化响应             | 统一 `{ success, data?, error?, requestId? }` |
-| `kit.validate.*`            | 请求体/查询/参数校验   | 失败 throw Response（SvelteKit 控制流）       |
-| `defineEndpoint(def)`       | 定义 EndpointDef 契约  | 与 api-client 配合使用                        |
-
-### EndpointDef 契约
-
-```typescript
-import { defineEndpoint } from '@h-ai/kit'
-import { z } from 'zod'
-
-const myEndpoint = defineEndpoint({
-  method: 'POST',
-  path: '/api/v1/items',
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string(), name: z.string() }),
-  requireAuth: true,
-})
-```
-
-## 错误码（常见）
-
-### API 响应错误码（`kit.response`）
-
-| code               | status | 场景               |
-| ------------------ | ------ | ------------------ |
-| `BAD_REQUEST`      | 400    | 参数或请求格式错误 |
-| `UNAUTHORIZED`     | 401    | 未认证             |
-| `FORBIDDEN`        | 403    | 无权限             |
-| `NOT_FOUND`        | 404    | 资源不存在         |
-| `CONFLICT`         | 409    | 资源冲突           |
-| `VALIDATION_ERROR` | 422    | 数据校验失败       |
-| `INTERNAL_ERROR`   | 500    | 未处理异常         |
-
-## API 契约范式（端到端类型安全）
-
-> `kit.fromContract` 和 `api.call` 共同消费模块 `api/` 下的 `EndpointDef`，实现服务端↔客户端的全链路类型安全 + 运行时 Zod 校验。
-
-### 服务端流程（本模块责任）
-
-1. 从 `@h-ai/xx/api` 导入 `xxEndpoints`
-2. `kit.fromContract(xxEndpoints.xxx, handler)` → 自动 Zod 校验入参 → handler 获得类型安全的 `input`
-3. 需权限时在 handler 内调用 `kit.guard.require`
-
-### 多模块契约示例
-
-```typescript
-// ─── 存储：预签名上传 ───
-import { storageEndpoints } from '@h-ai/storage/api'
-import { storage } from '$lib/server/init'
-
-export const POST = kit.fromContract(storageEndpoints.presignUpload, async (input, event) => {
-  kit.guard.require(event.locals.session, 'storage:write')
-  const result = await storage.presign.putUrl(input.key, input)
-  if (!result.success) {
-    return kit.response.internalError(result.error.message)
-  }
-  return kit.response.ok({ url: result.data, key: input.key })
-})
-
-// ─── IAM：登录 ───
-import { iamEndpoints } from '@h-ai/iam/api'
-import { iam } from '$lib/server/init'
-
-export const POST = kit.fromContract(iamEndpoints.login, async (input) => {
-  const result = await iam.auth.login(input)
-  if (!result.success) {
-    return kit.response.unauthorized(result.error.message)
-  }
-  return kit.response.ok(result.data)
-})
-
-// ─── 支付：创建订单 ───
-import { paymentEndpoints } from '@h-ai/payment/api'
-import { payment } from '$lib/server/init'
-
-export const POST = kit.fromContract(paymentEndpoints.createOrder, async (input, event) => {
-  kit.guard.require(event.locals.session, 'payment:create')
-  const result = await payment.order.create(input)
-  if (!result.success) {
-    return kit.response.internalError(result.error.message)
-  }
-  return kit.response.created(result.data)
-})
-```
-
-## 常见模式
-
-### 契约模式（推荐新项目使用）
-
-1. 在模块的 `api/` 目录定义 `EndpointDef`（Zod schema）
-2. 服务端用 `kit.fromContract(endpoint, handler)` 处理
-3. 客户端用 `api.call(endpoint, input)` 调用
-4. 入参/出参全链路类型安全 + 运行时校验
-
-### CORS + Capacitor 配置
-
-Capacitor 原生 App 的 WebView 发送的请求并非 CORS 同源，需要配置：
-
-```typescript
-cors: {
-  origins: ['https://your-api.com'],
-  capacitor: true,  // 自动添加 capacitor://* 和 ionic://* 等预设
-}
-```
-
-### 双构建模式
-
-```typescript
-// svelte.config.js
-import { createAdapter } from '@h-ai/kit/adapter'
-
-const config = {
-  kit: {
-    adapter: createAdapter(),
-    // VITE_ADAPTER=static → adapter-static (SPA)
-    // VITE_ADAPTER=node   → adapter-node (SSR)
-    // 默认 → adapter-node
-  },
-}
-```
-
-## 相关 Skills
-
-- `hai-core`：全局配置、日志、HaiResult 基础能力
-- `hai-iam`：Token 认证、角色权限模型
-- `hai-api-client`：客户端契约调用（SPA / 原生 App 场景）
-- `hai-crypto`：传输加密与密钥管理能力
-- `hai-capacitor`：原生 App CORS 场景
-
----
-
-## 浏览器侧使用
-
-### 创建统一 API 客户端 — `kit.client`
-
-> **所有浏览器端 API 请求必须通过 `apiFetch`，禁止直接 `fetch()`。**
-
-在 `src/lib/utils/api.ts` 中一次性创建，全应用共享：
-
-```typescript
-// src/lib/utils/api.ts
-import { kit } from '@h-ai/kit'
-
-const client = kit.client.create({
-  auth: true, // 自动从 localStorage 注入 Bearer Token
-})
-
-export const { apiFetch } = client
-```
-
-如需传输加密，传入 crypto：
-
-```typescript
-import { crypto } from '@h-ai/crypto'
-import { kit } from '@h-ai/kit'
-
-if (typeof window !== 'undefined') {
-  crypto.init() // 浏览器端初始化加密模块
-}
-
-const client = kit.client.create({
-  transport: { crypto }, // 透明完成密钥交换 + 请求/响应体加解密
-  auth: true,
-})
-
-export const { apiFetch } = client
-```
-
-`apiFetch` 自动处理：
-- **CSRF**：写方法（POST/PUT/DELETE）自动读取 `hai_csrf` Cookie 并设置 `X-CSRF-Token`
-- **Bearer Token**：自动从 localStorage 读取并注入 `Authorization` header
-- **传输加密**：可选，首次写请求时自动密钥交换
-
-使用示例：
-
-```typescript
-// ✅ 正确方式
-import { apiFetch } from '$lib/utils/api'
-
-const res = await apiFetch('/api/users', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify(data),
-})
-
-// ❌ 禁止在组件中直接 fetch
-// const res = await fetch('/api/users', { ... })
-```
-
-### Token 存储 — `kit.auth.createTokenStore`
-
-```typescript
-import { kit } from '@h-ai/kit'
-
-// 创建 localStorage 存储（Web 端默认）
-const tokenStore = kit.auth.createTokenStore('hai_access_token')
-tokenStore.set(tokens.accessToken) // 登录后保存
-tokenStore.get()                   // string | null
-tokenStore.clear()                 // 登出时清除
-```
-
-### hooks.client.ts 标准配置 — `kit.auth.createHandleFetch`
-
-```typescript
-// src/hooks.client.ts
-import { kit } from '@h-ai/kit'
-
-// 自动为同源请求附加 Authorization: Bearer <token>
-export const handleFetch = kit.auth.createHandleFetch()
-```
-
-### 选择指南：kit.client vs api-client
-
-| 场景 | 推荐 | 原因 |
-|------|------|------|
-| SSR SvelteKit 应用（同源请求） | `kit.client.create().apiFetch` | 自动 CSRF、同源 Cookie 透传、传输加密 |
-| SPA / 原生 App（跨域请求） | `api.init()` + `api.call()` | 完整 Token 管理、401 自动刷新 |
-| 服务端 `+page.server.ts` | 直接调用模块 API | 无需 HTTP 自环 |
-| 契约调用（类型安全） | `api.call(endpoint, input)` | EndpointDef 双向 Zod 校验 |
+`kit.auth.logout(cookies, accessToken)` 返回 `Promise<HaiResult<void>>`。无令牌时仅清除 Cookie 并成功；有令牌但未配置认证操作时返回失败。无论服务端结果如何都清除本地 Cookie，调用方仍必须把失败转换为错误响应或提示；仅成功结果代表服务端撤销已经确认。底层控制流异常继续传播。

package/templates/skills/hai-kit/reference.md

@@ -0,0 +1,202 @@
+# hai-kit 参考
+
+> `@h-ai/kit` 只负责 SvelteKit 集成：`handle` hook、guard、response、validate、client、auth、crud、A2A。公共跨端 HTTP API 契约统一使用 `@h-ai/api-contract` + `@h-ai/serv`，不要在 kit 中定义业务 API contract。
+
+认证协议仅支持 v2：独立随机 SM4-CBC 密钥和 HMAC-SM3 密钥由 SM2 封装，先验签、再验证 MAC，最后解密 CBC。请求由客户端私钥签名，响应由所选服务端版本签名。认证字段包括 version、direction、serverKeyId、clientId、128 位随机 requestId（兼 nonce）、issuedAt、HTTP method、pathname + 原始 search 的 SM3 pathHash，以及响应 status。请求有效期 5 分钟，未来时钟偏差最多 30 秒；共享 registry 原子消费 (clientId, requestId)，nonce 至少保留到 issuedAt + 6 分钟以覆盖节点偏差，存储故障拒绝请求。Redis 必须保留有效 nonce，使用 noeviction/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
+
+空 POST 也发送空明文的认证封装；GET/HEAD 将封装放在 X-Hai-Transport 头，204/304/HEAD 等无正文响应也使用同名头承载认证封装。其它请求/响应在 JSON 正文承载封装并带 X-Encrypted: true。客户端必须关联原请求上下文和 HTTP status，缺标记、旧格式或认证失败一律 reject；明文接口由 Serv/Kit 路径规则 `encryption: disabled` 或宿主 `excludePaths` 显式允许；调用方同步选择普通请求，API Client/Kit 包装器使用自己的 `excludePaths`。CORS 须允许并暴露 X-Hai-Transport。握手公钥的真实性依赖 TLS，不替代 IAM 业务授权。
+
+## 使用步骤
+
+### 1. 请求管道
+
+```ts
+import type { Handle } from '@sveltejs/kit'
+import { cache } from '@h-ai/cache'
+import { kit } from '@h-ai/kit'
+
+const haiHandle = kit.createHandle({
+  auth: {
+    verifyToken: async token => token ? { userId: 'u_1', roles: ['admin'], permissions: ['user:read'] } : null,
+    loginUrl: '/auth/login',
+    protectedPaths: ['/admin/*'],
+  },
+  rateLimit: { windowMs: 60_000, maxRequests: 100, store: kit.middleware.createCacheRateLimitStore(cache, { namespace: 'app' }) },
+  logging: true,
+})
+
+export const handle: Handle = haiHandle
+```
+
+限流采用首次成功提交为起点的固定窗口，后续请求不延长 TTL。必须显式传 store；应用先检查共享 Redis 初始化结果，所有节点使用相同 namespace/windowMs/maxRequests。缓存读取/条件提交失败或冲突耗尽返回503，超限429；不会回退 get+set 或本地计数。createMemoryRateLimitStore 仅开发或显式 HAI_E2E/HAI_E2E_MOCK 测试使用，无常驻定时器，丢弃引用即可回收；每次请求最多惰性扫描 64 项，最多保存 10000 个窗口，容量满时对新 key 返回503且不驱逐有效计数，外部 store 生命周期由创建者管理；生产不得设置测试开关。响应重置时间为节点时钟估算，实际窗口由 Redis TTL 决定，须同步时钟。默认键只读取可信 adapter 的 getClientAddress、规范化等价IPv6和IPv4映射地址，不采信原始转发头；代理信任通过部署adapter配置。
+
+### 2. SvelteKit API endpoint
+
+```ts
+import { kit } from '@h-ai/kit'
+import { z } from 'zod'
+
+const CreateUserSchema = z.object({ name: z.string().min(1) })
+
+export const POST = kit.handler(async ({ request, locals }) => {
+  kit.guard.require(locals.session, 'user:create')
+  const payload = await kit.validate.body(request, CreateUserSchema)
+  return kit.response.created(payload)
+})
+```
+
+### 3. 浏览器同源请求
+
+```ts
+import { kit } from '@h-ai/kit'
+
+const client = kit.client.create()
+export const { apiFetch } = client
+```
+
+> 同源 endpoint 使用 httpOnly Cookie；`auth: true` 只读取 `kit.auth.setBrowserToken()` 写入的页面内存 Token。自定义 `BrowserTokenStore` 也须使用内存或平台安全存储，禁止把敏感凭据持久化到 Web Storage。
+
+### 4. 同源传输加密
+
+kit 不再维护本地传输加密实现；服务端和客户端都统一委托 `@h-ai/crypto` 的 `crypto.transport`。
+
+```ts
+// hooks.server.ts
+import { cache } from '@h-ai/cache'
+import { createRedisTransportKeyStore, crypto, parseTransportServerKeyRing } from '@h-ai/crypto'
+import { kit } from '@h-ai/kit'
+
+await crypto.init()
+const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+if (!ring.success)
+  throw new Error(ring.error.message)
+const serverKeyRing = ring.data
+await cache.init({ type: 'redis', host: '127.0.0.1', port: 6379 })
+
+export const handle = kit.createHandle({
+  auth: {
+    verifyToken,
+    protectedPaths: ['/api/*'],
+    publicPaths: ['/api/_hai/*'],
+  },
+  crypto: {
+    crypto,
+    transport: {
+      serverKeyRing,
+      keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
+    },
+  },
+})
+```
+
+需要保护会话 Cookie 时配置 `crypto.encryptedCookies`，并通过 `crypto.cookieEncryptionKey` 或 `HAI_KIT_COOKIE_KEY` 提供密钥。缺少密钥会在 `createHandle()` 时失败；加解密错误不会回退到明文 Cookie。
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang='ts'>
+  import { browser } from '$app/environment'
+  import type { LayoutData } from './$types'
+  import { crypto } from '@h-ai/crypto'
+  import { kit } from '@h-ai/kit'
+  import { untrack } from 'svelte'
+
+  const { data }: { data: LayoutData } = $props()
+
+  // 服务端 layout 只返回 kit 公共投影；初次加载安装，不下发完整策略。
+  if (browser) {
+    kit.client.installBrowserTransport(untrack(() => data.kit), { crypto })
+  }
+</script>
+```
+
+```ts
+// lib/utils/api.ts —— 业务层只看到 apiFetch
+import { kit } from '@h-ai/kit'
+
+export const { apiFetch } = kit.client.create()
+```
+
+默认协商端点：`/api/_hai/key-exchange`。如 `keyExchangePath` 自定义，浏览器端同步设置 `keyExchangeUrl`。
+
+启用 transport 使用 `{ serverKeyRing, keyStore, ...公开路径配置 }`，两项必填，不再接受单独的 true。serverKeyRing 通过服务端 Secret/私有 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING` 安全解析，不放 `_kit.yml`、PUBLIC_/VITE_ 或日志；浏览器仅需公开 transport 配置和 crypto。各节点使用同一版本化 ring 与共享 Redis/数据库 registry；仅共享客户端公钥不够。请求带协商 serverKeyId，无需 sticky session；轮换先分发新旧 ring，再切 activeKeyId 重建 manager，删除旧 ID 后客户端 destroy 并重协商。开发/测试须显式选择内存 registry；原公开 maxClients 已删除。完整轮换步骤见 hai-crypto。
+
+transport 默认保护同源 `/api/*` endpoint 与 SvelteKit `__data.json` 页面数据请求；页面文档、静态资源与 `multipart/form-data` 上传请求保持明文透传。
+
+受保护路径不允许协议降级；缺少认证、管理器不可用、响应加密失败均拒绝。明文接口通过请求规则 encryption:disabled 或宿主 excludePaths 显式配置，调用方同步选择协议；IP、时间和认证继续检查。规则 required 优先于宿主排除表，冲突或缺少加密装配会拒绝创建 Handle。
+
+空 POST 也发送空明文的认证封装；GET/HEAD 将封装放在 X-Hai-Transport 头，204/304/HEAD 等无正文响应也使用同名头承载认证封装。其它请求/响应在 JSON 正文承载封装并带 X-Encrypted: true。客户端必须关联原请求上下文和 HTTP status，缺标记、旧格式或认证失败一律 reject；明文接口由 Serv/Kit 路径规则 `encryption: disabled` 或宿主 `excludePaths` 显式允许；调用方同步选择普通请求，API Client/Kit 包装器使用自己的 `excludePaths`。CORS 须允许并暴露 X-Hai-Transport。握手公钥的真实性依赖 TLS，不替代 IAM 业务授权。
+
+业务容量统一配置 transport.maxPlaintextBytes：UTF-8 JSON 明文字节，默认 1 MiB，有效整数范围 1 KiB～64 MiB，请求和响应共用。客户端从握手获取服务端预算，可选本地上限取较小值；resolveTransportBodyLimits(limit, { requiredPlaintextBytes }) 合并模块需求：保留显式上限，不足时报配置冲突；省略时按需要推导，无模块需要仍为 1 MiB。Serv/Kit 的 auto 规范化为 undefined。密文预算为两倍明文加 32 KiB。握手 JSON 16 KiB、公钥 4 KiB、认证头 16 KiB、路径 8 KiB、认证及防重放保持独立。原流超限/取消立即停止、取消并释放 reader；请求 413、响应返回加密的 500 容量错误，客户端识别 TransportBodyTooLargeError / hai:crypto:070。 通过 _kit.yml 的 transport.maxPlaintextBytes 或对应 HAI_*_TRANSPORT_MAXPLAINTEXTBYTES 配置并转发到服务端 transport；重建正文保留 signal 并删除旧长度/编码头。
+
+### 5. 使用 `_kit.yml` 统一 transport 配置
+
+`@h-ai/kit` 现在提供 `KitConfigSchema` / `resolveKitConfig()`，适合同一份 `_kit.yml`
+同时驱动 `hooks.server.ts` 与浏览器端 `kit.client.installBrowserTransport()`：
+
+```yml
+server:
+  host: 127.0.0.1
+  port: 3000
+
+transport:
+  keyExchangePath: /api/_hai/key-exchange
+  excludePaths:
+    - /api/storage
+    - /api/public
+    - /api/auth/profile/avatar
+```
+
+```ts
+import { core } from '@h-ai/core'
+import { KitConfigSchema } from '@h-ai/kit'
+
+// src/routes/+layout.server.ts；服务端已先完成应用配置初始化。
+export function load() {
+  const loaded = core.config.load('kit', './config/_kit.yml', KitConfigSchema)
+  if (!loaded.success)
+    throw new Error(loaded.error.message)
+  return { kit: { transport: loaded.data.transport } }
+}
+```
+
+`resolveKitConfig()` 同时解析 `server`（host/port）与 `transport`；host/port 优先级为 `HOST` / `PORT` 环境变量 > `_kit.yml` 的 `server` > 默认 `127.0.0.1:3000`（与 `@h-ai/serv` 同构）。
+`_kit.yml` 在服务端读取，可包含 access 和 trustedProxies；layout data 只投影公开 transport，不通过 ?raw 导入完整文件到浏览器，也不放密钥。如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。请求策略按[共享约定](../hai-core/request-access.md)装配与验证。
+
+子目录部署从 `$app/paths` 取 `base`，服务端 `crypto.transport.basePath` 与客户端 `installBrowserTransport(config, { crypto, basePath: base })` 同步；独立 client 的 `transport.basePath` 也用该值。默认空字符串为根目录，不能仅调整资源地址后把登录成功当作加密验证。交换/排除/容量路径保持完整请求路径，验证原始请求带加密标记、缺协议被拒绝、排除接口正常且不影响相邻目录。
+
+## 核心 API
+
+| API                                                      | 用途                                                     |
+| -------------------------------------------------------- | -------------------------------------------------------- |
+| `kit.createHandle()`                                     | 创建 SvelteKit Handle                                    |
+| `kit.sequence()`                                         | 组合多个 Handle                                          |
+| `kit.handler()`                                          | API endpoint 错误边界                                    |
+| `kit.guard.require()`                                    | 权限守卫                                                 |
+| `kit.response.*`                                         | 统一响应工厂                                             |
+| `kit.validate.*`                                         | Zod 请求校验                                             |
+| `kit.auth.*`                                             | Cookie / Token 辅助                                      |
+| `kit.client.create()`                                    | 浏览器端同源 apiFetch                                    |
+| `kit.client.installBrowserTransport(config, { crypto })` | 接收 KitPublicConfig，只含 transport；不要求浏览器接收代理或访问策略 |
+| `kit.client.installBrowserTransportFetch()`              | 底层入口：直接传 transport 配置安装浏览器全局 fetch 包装 |
+| `kit.crud.define()`                                      | 声明式 CRUD 资源                                         |
+
+`guard.require` 和 `validate` 的 OrFail Response 仅由 `kit.handler` 处理 API 控制流。页面 load 用 guard.check 加 SvelteKit error，查询参数先 safeParse；不能把 API Response 直接抛给页面运行时。
+
+## 常见模式
+
+- SvelteKit 应用内同源请求用 `kit.client.create().apiFetch`。
+- SvelteKit 应用启用 transport 时，服务端 layout 只投影 transport 为公共 data；`+layout.svelte` 的 `if (browser)` 分支调用一次安装器，无需复制 `keyExchangeUrl` / `excludePaths`，不下发完整配置。
+- Web/App/小程序跨域访问公共 API 用 `@h-ai/api-client` typed client。
+- 传输加密只通过 `crypto.transport` 间接装配，不在 kit 中新增本地加密工厂或鸭子类型。
+- 服务端业务模块直接调用模块 API，不通过 HTTP 自环。
+- API endpoint 必须用 Zod 校验用户输入，并设置认证/权限边界。
+
+## 声明式 CRUD 表单字段
+
+`kit.crud.define` 的字段支持 `colSpan: 'auto' | 1 | 2`，以及 `validation.message: string | (() => string)`。布局通过 UI 的 `CrudPage.form` 配置；客户端校验用于交互提示，服务端仍使用 Zod 验证和现有权限守卫。UI 公共契约见相邻 [hai-ui skill](../hai-ui/SKILL.md)。
+
+Node 请求/SSR 必须用 `core.i18n.runWithLocale(locale, callback)`（kit 同名方法）包裹实际异步 resolve；serv 自动建立请求语言上下文。浏览器 setGlobalLocale/createLocaleStore 继续管理应用语言，SSR 的 UI setter/store 不写全局值。显式 MessageOptions.locale 优先；进程默认语言仅在启动时设置。
+
+认证 Cookie 在 NODE_ENV 或 HAI_CORE_ENV 为 production 时默认启用 Secure，HAI_E2E/HAI_E2E_MOCK 不降低 Cookie 安全；限流生产判断也识别这两个环境标志，测试开关仅放宽共享状态要求。
+
+`kit.auth.logout(cookies, accessToken)` 返回 `Promise<HaiResult<void>>`。无令牌时仅清除 Cookie 并成功；有令牌但未配置认证操作时返回失败。无论服务端结果如何都清除本地 Cookie，调用方仍必须把失败转换为错误响应或提示；仅成功结果代表服务端撤销已经确认。底层控制流异常继续传播。