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

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

@@ -34,13 +34,15 @@
 ```typescript
 import { core } from '@h-ai/core'
 
-// 自动加载 config/ 目录下的所有 _*.yml 和 *.yml
+// 自动加载运行时 .yml / .yaml，跳过 _deploy.yml / _deploy.yaml
 core.init({ configDir: './config' })
 
 // 也可指定日志级别和配置监听
 core.init({ configDir: './config', watchConfig: true })
 ```
 
+`_deploy.yml` / `_deploy.yaml` 由部署 CLI 在加载目标环境与凭据后独立解析，不参加 Core 的自动加载和监听；业务 `deploy.yml`、手动 `core.config.load` 不受影响。单项 `config.load` 返回失败时记录错误并继续，应用须 validate 必需配置并检查 success。目录扫描、日志设置等异常仍可能传播，不能把同步 void 当作所有配置加载成功的证明。
+
 ### 2. 使用功能
 
 ```typescript
@@ -60,7 +62,7 @@ const formErrors = core.zodValidation.mapZodErrorToFormErrors(zodError, getMessa
 
 | 方法        | 签名                              | 说明                                      |
 | ----------- | --------------------------------- | ----------------------------------------- |
-| `core.init` | `(options?: CoreOptions) => void` | 初始化（同步，加载配置目录中的所有 YAML） |
+| `core.init` | `(options?: CoreOptions) => void` | 同步加载运行时 YAML，排除两个 `_deploy` 保留文件 |
 
 > `CoreOptions`：`{ logging?: Partial<LoggingConfig>, configDir?: string, watchConfig?: boolean }`
 >
@@ -150,6 +152,8 @@ core.logger.error('Failed to connect', { error })
 core.logger.debug('Processing item', { id, step: 'validation' })
 ```
 
+原生 `Error` 的 `name/message/stack/cause`、`AggregateError.errors` 与可枚举自有上下文先转成副本，再走字段/URL 脱敏与附加 `redact`；两端原异常均不变。Error 子图循环用 `[Circular]`，达到 32 层用 `[MaxDepth]`，自定义替换值也经过同一规范化；普通对象的循环与替换语义不变。自由文本不会自动解析秘密，可配置 `redact: ['error.message', 'error.stack']` 遮蔽整条诊断路径。
+
 **管理方法**：
 
 | 方法        | 签名                                   | 说明                     |
@@ -195,18 +199,21 @@ const level = core.logger.getLevel() // 'debug'
 | 方法                  | 签名                                                                  | 说明           |
 | --------------------- | --------------------------------------------------------------------- | -------------- |
 | `getGlobalLocale`     | `() => string`                                                        | 获取当前语言   |
-| `setGlobalLocale`     | `(locale: string) => void`                                            | 设置全局语言   |
+| `setGlobalLocale`     | `(locale: string) => void`                                            | 浏览器语言/启动默认值；请求内只改当前上下文 |
+| `runWithLocale`       | `<T>(locale: string, callback: () => T) => T`                           | Node 请求/SSR 异步语言隔离 |
 | `createMessageGetter` | `(messages: Record<string, Record<string, string>>) => MessageGetter` | 创建消息获取器 |
 
 创建模块 i18n：
 
 ```typescript
 import enUS from '../messages/en-US.json'
+import jaJP from '../messages/ja-JP.json'
 import zhCN from '../messages/zh-CN.json'
 
 const m = core.i18n.createMessageGetter({
   'zh-CN': zhCN,
   'en-US': enUS,
+  'ja-JP': jaJP,
 })
 
 // 使用
@@ -301,7 +308,7 @@ core.id.isValidNanoId('abc123', 6)     // true/false
 
 - 生成 UUID **一律用 `core.id.uuid()`**，禁止裸调 `crypto.randomUUID()`。
 - 原因：`crypto.randomUUID` 仅在**安全上下文（HTTPS / localhost）**下可用，生产 http 环境会抛
-  `crypto.randomUUID is not a function`；`core.id.uuid()` 已做 `randomUUID → getRandomValues → Math.random` 三级兜底，Node.js 与浏览器通用。
+  `crypto.randomUUID is not a function`；`core.id.uuid()` 仅使用 randomUUID 或密码学安全的 getRandomValues；两者不可用时明确抛错，绝不降级到 Math.random。
 - 需要不带横线的 compact 形式：`core.id.uuid().replaceAll('-', '')`。
 - 代码评审与新建代码时以此为准，发现裸调 `crypto.randomUUID()` 一律改走 `core.id.uuid()`。
 
@@ -328,7 +335,7 @@ core.object.omit(obj, ['c', 'd'])
 ```typescript
 core.string.capitalize('hello')      // 'Hello'
 core.string.kebabCase('helloWorld')  // 'hello-world'
-core.string.constantTimeEqual(a, b)  // 防时序攻击比较
+core.string.constantTimeEqual(a, b)  // Node 使用原生等长比较；浏览器不保证恒时
 ```
 
 #### 数组操作 — `core.array`
@@ -533,3 +540,16 @@ logger.debug('Data fetched', { count: items.length })
 | context 输出 | pretty 追加 JSON 上下文，json 合并上下文到结构化 JSON 字符串 |
 
 云资源输出格式与部署配置消费见 [hai-deploy](../hai-deploy/SKILL.md)；这里的父节点覆盖规则同样适用。
+
+### URL 日志脱敏
+
+使用 `core.sanitize.sanitizeUrl(url)` 统一处理连接地址；它会遮蔽用户名、密码、敏感 query 参数和 OAuth 键值 fragment。非法地址返回固定占位符。`sanitizeSensitiveFields` 对 URL 类字段使用同一规则；自定义 matcher 同样匹配参数名，不能只遮蔽 userinfo 后记录含 token 的 URL。
+
+```ts
+const safeUrl = core.sanitize.sanitizeUrl("https://example.com/a?token=value&limit=10")
+// https://example.com/a?token=[REDACTED]&limit=10
+```
+
+Node 请求/SSR 必须用 `core.i18n.runWithLocale(locale, callback)`（kit 同名方法）包裹实际异步 resolve；serv 自动建立请求语言上下文。浏览器 setGlobalLocale/createLocaleStore 继续管理应用语言，SSR 的 UI setter/store 不写全局值。显式 MessageOptions.locale 优先；进程默认语言仅在启动时设置。
+
+Node 入口的 core.string.constantTimeEqual 将原始 UTF-16 单元编码后使用 node:crypto.timingSafeEqual 比较等长字节，长度不相同时直接 false，长度本身不受保护。浏览器实现仅避免按内容提前返回，不提供 JavaScript 引擎级恒时保证，不用于服务端凭证校验。外围分支、编码和请求处理不因此自动成为恒时。

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

@@ -1,271 +1,43 @@
 ---
 name: hai-crypto
-description: "使用 @h-ai/crypto 进行 SM2/SM3/SM4、密码哈希与传输加密。"
+description: "实现 SM2/SM3/SM4 加解密、验签、密码哈希，或通过 serv/kit/api-client 接入传输加密。"
 ---
 
 # hai-crypto
 
+transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、5 分钟窗口、nonce 持久化与实现示例见 [参考](reference.md)。
+
 ## 能力契约
 
 | 项目 | 契约 |
 | --- | --- |
 | 能力 | 使用 @h-ai/crypto 进行 SM2/SM3/SM4、密码哈希与传输加密 |
 | 适用场景 | 应用加密、验签、密码保存或传输保护 |
-| 输入 | CryptoConfigInput、字节/文本、密钥和 transport 装配选项 |
+| 输入 | 无参 init、字节/文本、密钥和 transport 装配选项 |
 | 输出 | 加解密/验签的 HaiResult；transport 工厂按公开类型使用 |
-| 限制 | 先 init；password 仅服务端，浏览器仅支持部分能力。传输通过 serv/kit/api-client 顶层装配，不导入内部工厂。 |
-
-> `@h-ai/crypto` 提供非对称加密、哈希、对称加密与密码哈希能力，支持 Node.js 与浏览器双端。
-
-## 运行环境
-
-**Node.js + 浏览器双端可用。** 浏览器端通过 `crypto.init()` 初始化（无需配置参数）。
-
-| 能力 | Node.js | 浏览器 | 说明 |
-|------|---------|--------|------|
-| `crypto.asymmetric` 非对称加密 | ✅ | ✅ | SM2 加解密、签名验签 |
-| `crypto.hash` 哈希 | ✅ | ✅ | SM3 哈希、HMAC |
-| `crypto.symmetric` 对称加密 | ✅ | ✅ | SM4 ECB/CBC |
-| `crypto.password` 密码哈希 | ✅ | ❌ | 依赖 Node.js crypto（服务端专用） |
-| `crypto.transport` 传输加密 | ✅ | ✅ | 服务端管理器 + 客户端 encryptedFetch |
-
-浏览器端主要用于 kit 传输加密场景（`kit.client.create({ transport: { crypto } })`），一般不需要直接调用 crypto API。
-
-## 适用场景
-
-- 非对称加密/解密、签名/验签、密钥生成
-- 哈希计算与 HMAC
-- 对称加密/解密（ECB/CBC 模式）
-- 密码存储与验证（加盐迭代哈希）
-- 传输加密：为 serv / kit / api-client 提供统一协议、密钥协商和请求响应加解密
-
-## 使用步骤
-
-### 1. 初始化与关闭
-
-```typescript
-import { crypto } from '@h-ai/crypto'
-
-await crypto.init()
-
-// 使用后关闭
-await crypto.close()
-```
-
-## 核心 API
-
-### 非对称加密 — `crypto.asymmetric`
-
-| 方法                | 签名                                                        | 说明         |
-| ------------------- | ----------------------------------------------------------- | ------------ |
-| `generateKeyPair`   | `() => HaiResult<KeyPair>`                                     | 生成密钥对   |
-| `encrypt`           | `(data, publicKey, options?) => HaiResult<string>`             | 公钥加密     |
-| `decrypt`           | `(ciphertext, privateKey, options?) => HaiResult<string>`      | 私钥解密     |
-| `sign`              | `(data, privateKey, options?) => HaiResult<string>`            | 私钥签名     |
-| `verify`            | `(data, signature, publicKey, options?) => HaiResult<boolean>` | 公钥验签     |
-| `isValidPublicKey`  | `(key: string) => boolean`                                  | 校验公钥格式 |
-| `isValidPrivateKey` | `(key: string) => boolean`                                  | 校验私钥格式 |
-
-```typescript
-const keyPair = crypto.asymmetric.generateKeyPair()
-if (keyPair.success) {
-  const { publicKey, privateKey } = keyPair.data
-
-  const encrypted = crypto.asymmetric.encrypt('敏感数据', publicKey)
-  if (encrypted.success) {
-    const decrypted = crypto.asymmetric.decrypt(encrypted.data, privateKey)
-  }
-
-  const signature = crypto.asymmetric.sign('待签名数据', privateKey)
-  if (signature.success) {
-    const valid = crypto.asymmetric.verify('待签名数据', signature.data, publicKey)
-  }
-}
-```
-
-**AsymmetricEncryptOptions**：`{ cipherMode?: 0 | 1, outputFormat?: 'hex' | 'base64' }`
-**SignOptions**：`{ hash?: boolean, userId?: string }`
-
-### 哈希 — `crypto.hash`
-
-| 方法     | 签名                                                       | 说明     |
-| -------- | ---------------------------------------------------------- | -------- |
-| `hash`   | `(data: string \| Uint8Array, options?) => HaiResult<string>` | 哈希     |
-| `hmac`   | `(data, key) => HaiResult<string>`                            | HMAC     |
-| `verify` | `(data, expectedHash) => HaiResult<boolean>`                  | 验证哈希 |
-
-```typescript
-const hash = crypto.hash.hash('hello')
-const hmac = crypto.hash.hmac('hello', 'secret-key')
-const valid = crypto.hash.verify('hello', hash.data!)
-```
-
-**HashOptions**：`{ inputEncoding?: 'utf8' | 'hex' }`
-
-### 对称加密 — `crypto.symmetric`
-
-| 方法            | 签名                                            | 说明                        |
-| --------------- | ----------------------------------------------- | --------------------------- |
-| `generateKey`   | `() => string`                                  | 生成 128-bit 密钥（32 hex） |
-| `generateIV`    | `() => string`                                  | 生成随机 IV（32 hex）       |
-| `encrypt`       | `(data, key, options?) => HaiResult<SymmetricEncryptedPayload>` | 加密（返回结构化密文）      |
-| `decrypt`       | `(payload, key) => HaiResult<string>`          | 解密结构化密文              |
-| `encryptWithIV` | `(data, key) => HaiResult<EncryptWithIVResult>`    | CBC 模式加密（自动生成 IV） |
-| `decryptWithIV` | `(ciphertext, key, iv) => HaiResult<string>`       | CBC 模式解密                |
-| `deriveKey`     | `(password, salt) => string`                    | 从密码和盐值派生密钥        |
-| `isValidKey`    | `(key: string) => boolean`                      | 校验密钥格式                |
-| `isValidIV`     | `(iv: string) => boolean`                       | 校验 IV 格式                |
-
-```typescript
-const key = crypto.symmetric.generateKey()
-
-// 默认安全用法：CBC + 自动 IV，返回 { mode, ciphertext, iv, encoding }
-const encrypted = crypto.symmetric.encrypt('明文数据', key)
-if (encrypted.success) {
-  const decrypted = crypto.symmetric.decrypt(encrypted.data, key)
-}
-
-// 需要单独存储 IV 时使用结构化结果
-const withIV = crypto.symmetric.encryptWithIV('明文数据', key)
-if (withIV.success) {
-  const decrypted = crypto.symmetric.decryptWithIV(withIV.data.ciphertext, key, withIV.data.iv)
-}
-```
-
-**SymmetricEncryptOptions**：`{ mode?: 'ecb' | 'cbc', iv?: string, outputFormat?: 'hex' | 'base64' }`
-**SymmetricEncryptedPayload**：`{ mode: 'ecb' | 'cbc', ciphertext: string, iv?: string, encoding: 'hex' | 'base64' }`
-
-> `encrypt()` 默认使用 CBC 并自动生成 IV。ECB 会泄漏明文结构，只有底层协议明确要求时才显式 `{ mode: 'ecb' }`。
-
-### 密码哈希 — `crypto.password`
-
-| 方法     | 签名                                    | 说明     |
-| -------- | --------------------------------------- | -------- |
-| `hash`   | `(password, config?) => HaiResult<string>` | 密码哈希 |
-| `verify` | `(password, hash) => HaiResult<boolean>`   | 验证密码 |
-
-```typescript
-const hashed = crypto.password.hash('MyPassword123')
-if (hashed.success) {
-  const valid = crypto.password.verify('MyPassword123', hashed.data)
-}
-```
-
-哈希格式：`$hai$<iterations>$<salt>$<hash>`
-**PasswordConfig**：`{ saltLength?: number, iterations?: number }`
-
-### 传输加密 — `crypto.transport`
-
-传输加密主工厂必须从 `crypto.transport` 访问；共享 `keyStore` provider 请从 `@h-ai/crypto` 根入口导入，不从子目录内部路径导入。
-
-| 方法 | 签名 | 说明 |
-| --- | --- | --- |
-| `createServer` | `(options?) => HaiResult<TransportEncryptionManager>` | 创建服务端传输加密管理器 |
-| `createClient` | `({ keyExchangeUrl, fetch? }) => TransportClient` | 创建客户端 encryptedFetch 会话 |
-| `protocol` | `TRANSPORT_PROTOCOL` | 协议常量：`X-Client-Id`、`X-Encrypted`、默认协商路径 |
-
-共享 `keyStore` provider（从 `@h-ai/crypto` 根入口导入）：
-
-| 工厂 | 签名 | 说明 |
-| --- | --- | --- |
-| `createInMemoryKeyStore` | `(maxClients?) => TransportKeyStore` | 默认 FIFO 内存实现 |
-| `createRedisTransportKeyStore` | `({ cache, ttlSeconds? }) => TransportKeyStore` | 基于 `@h-ai/cache` 的共享实现，通常配 Redis |
-| `createReldbTransportKeyStore` | `({ reldb, ttlSeconds? }) => TransportKeyStore` | 基于 `@h-ai/reldb` 的共享实现，自动建表 |
-
-```typescript
-const server = crypto.transport.createServer({ maxClients: 10000 })
-if (!server.success)
-  return server
-
-const client = crypto.transport.createClient({
-  keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange',
-})
-
-const resp = await client.encryptedFetch('https://api.example.com/api/v1/echo', {
-  method: 'POST',
-  body: JSON.stringify({ hello: 'world' }),
-})
-```
-
-```typescript
-import { createRedisTransportKeyStore, crypto } from '@h-ai/crypto'
-import { cache } from '@h-ai/cache'
-
-await cache.init({ type: 'redis', host: '127.0.0.1', port: 6379 })
-
-const sharedServer = crypto.transport.createServer({
-  keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
-})
-```
-
-使用流程：
-1. 先 `await crypto.init()`。
-2. 服务端 `createServer()` 后暴露一个 POST 密钥协商端点：接收 `clientPublicKey`，返回 `serverPublicKey + clientId`。
-3. 客户端 `createClient({ keyExchangeUrl })` 后，首次 `init()` / `encryptedFetch()` 会自动做密钥协商。
-4. 协商完成后，请求附带 `X-Client-Id`；若请求有 body，则自动包装成 `{ encryptedKey, ciphertext, iv }`。
-5. 服务端先 `decryptRequest()`，业务处理后再 `encryptResponse(clientId, data)`。
-6. 客户端收到 `X-Encrypted: true` 的响应后自动解密；`destroy()` 可清空当前会话。
-
-`encryptedFetch()` 与原生 fetch 一样会 reject：网络错误、密钥协商失败、请求加密失败或响应解密失败都应在调用方按 fetch 错误处理策略捕获。
-
-常规应用优先使用上层封装：
-- serv：`serv.createApp({ transport: { crypto } })`
-- kit：`kit.createHandle({ crypto: { crypto, transport: true } })` + `kit.client.create({ transport: { crypto } })`
-- api-client：`apiClient.init({ transport: { crypto } })`
-
-## 错误码 — `HaiCryptoError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiCryptoError.INVALID_INPUT` | `hai:crypto:002` | 无效输入 |
-| `HaiCryptoError.INVALID_KEY` | `hai:crypto:003` | 无效密钥 |
-| `HaiCryptoError.NOT_INITIALIZED` | `hai:crypto:010` | 未初始化 |
-| `HaiCryptoError.INIT_FAILED` | `hai:crypto:011` | 初始化失败 |
-| `HaiCryptoError.KEY_GENERATION_FAILED` | `hai:crypto:020` | 密钥生成失败 |
-| `HaiCryptoError.ENCRYPTION_FAILED` | `hai:crypto:021` | 加密失败 |
-| `HaiCryptoError.DECRYPTION_FAILED` | `hai:crypto:022` | 解密失败 |
-| `HaiCryptoError.SIGN_FAILED` | `hai:crypto:023` | 签名失败 |
-| `HaiCryptoError.VERIFY_FAILED` | `hai:crypto:024` | 验签失败 |
-| `HaiCryptoError.HASH_FAILED` | `hai:crypto:040` | 哈希计算失败 |
-| `HaiCryptoError.HMAC_FAILED` | `hai:crypto:041` | HMAC 计算失败 |
-| `HaiCryptoError.INVALID_IV` | `hai:crypto:060` | 无效 IV |
-
-## 常见模式
-
-### 数据加密存储
-
-```typescript
-const key = process.env.HAI_CRYPTO_DATA_KEY!
-const encrypted = crypto.symmetric.encrypt(sensitiveData, key)
-// 存入数据库
+| 限制 | crypto 操作先 init；readTransportBody/parseTransportServerKeyRing 为无需 init 的纯工具。password 仅服务端，浏览器仅支持部分能力。传输通过 serv/kit/api-client 顶层装配，不导入内部工厂。 |
 
-// 读取时解密
-const decrypted = crypto.symmetric.decrypt(storedPayload, key)
-```
+## 使用路径
 
-> 默认密文是结构化对象，必须完整存储 `mode` / `ciphertext` / `iv` / `encoding` 字段；如果数据库字段已拆分 IV 与密文，请改用 `encryptWithIV()` / `decryptWithIV()`。
+1. `crypto.init()` 无配置参数，检查结果；确认目标端是否支持所需能力，password 仅 Node。
+2. 选用公开 asymmetric/hash/symmetric/password 操作，检查 HaiResult；SM3 HMAC 不等同于 SHA-256 HMAC。SM4 使用 `symmetric.generateKey()` 生成随机密钥，不提供密码 KDF；密码存储使用服务端 `password.hash()`。
+3. 传输加密经 serv/kit/api-client 顶层配置接入，统一协商与刷新路径；不导入内部工厂。
 
-### 密码存储与验证
+握手公钥先用无需 init 的 `isValidSM2PublicKey` 验证编码和 SM2 曲线点；内置 manager/registry 也校验，serv/kit 在写存储前拒绝。DB registry 用事务共享容量（maxClients 默认 10000、各节点一致），满容量拒绝、不驱逐有效 nonce；配置有限 ttlSeconds，并由应用周期调用 DB 工厂返回的 `pruneExpired()`（每次公钥/nonce 各最多 100 条）。Redis 使用原生 TTL，容量由部署管理。TTL 显式值只能为正整数秒，详见参考中的范围和迁移边界。
 
-```typescript
-// 注册时哈希存储
-const hashResult = crypto.password.hash(userPassword)
-if (hashResult.success) {
-  // 存储 hashResult.data 到数据库
-}
+服务端必须显式注入受管 `serverKeyRing` 与共享 `keyStore`，没有进程随机私钥或内存 registry 默认值。请求携带协商 serverKeyId；各节点同 ring + registry 支持跨节点、重启和新旧版本轮换。密钥只从 Secret/私有环境注入，不进入公开配置、客户端或日志。开发/测试的内存 registry 须显式选择。
 
-// 登录时验证
-const verifyResult = crypto.password.verify(inputPassword, storedHash)
-if (verifyResult.success && verifyResult.data) {
-  // 密码匹配
-}
-```
+传输字节预算统一使用根入口 `TRANSPORT_BODY_LIMITS`：握手 JSON 16 KiB、公钥 4 KiB、明文 1 MiB、密文 JSON 2 MiB + 32 KiB。自定义适配器用纯函数 `readTransportBody` 消费原流并有界读取；不要 clone/tee。客户端握手超时 30 秒；取消和超限释放 reader，异常密文响应 reject。
+4. 验证加解密往返、错误密钥/签名和关闭，密钥与明文不写日志或浏览器公开配置。
 
-## 相关 Skills
+## 按需参考
 
-- `hai-core`：配置与 HaiResult 模型
-- `hai-iam`：密码哈希（内部自动调用 crypto.password）
-- `hai-kit`：SvelteKit 集成（传输加密）
-- `hai-serv` / `hai-api-client`：跨域 HTTP API 的透明传输加密
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-管理端在线加密演示直接调用 Crypto SM3/SM4 API，SM4 使用随机临时密钥和 IV，并在显示成功前解密校验；密钥不保存。输入改变即清空旧结果，禁止用随机摘要或 Base64 伪装算法结果。
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [错误码 — `HaiCryptoError`](reference.md#错误码--haicryptoerror)
+- [常见模式](reference.md#常见模式)
+- [相关 Skills](reference.md#相关-skills)