@h-ai/crypto 0.1.0-alpha.65 → 0.1.0-alpha.67

package/README.en.md

@@ -4,9 +4,11 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/cache](../cache/README.en.md) · [@h-ai/core](../core/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
 
+## Introduction
+
 A cryptography module for asymmetric encryption, hashing, symmetric encryption, and password hashing.
 
-## Capabilities
+## Core features
 
 - Asymmetric cryptography (key generation, encryption/decryption, signing/verification)
 - Hashing (hash, HMAC, verification)
@@ -15,22 +17,26 @@ A cryptography module for asymmetric encryption, hashing, symmetric encryption,
 - Transport encryption (`crypto.transport`: server manager + client `encryptedFetch`)
 - Shared server/browser support (Node.js / browser)
 
-## Security notice
+## Getting started
+
+### Security notice
 
 - **SM4 encryption returns a structured payload by default**: `crypto.symmetric.encrypt(data, key)` uses CBC + a random IV by default and returns `{ mode, ciphertext, iv, encoding }`. Pass that object to `crypto.symmetric.decrypt(payload, key)` to decrypt.
 - **SM4 `deriveKey(password, salt)` is not a KDF**: it performs a single SM3 hash and offers no resistance to password cracking. **Never use it for password storage**. Use `crypto.password.hash(password)` for password hashing and PBKDF2 / scrypt / Argon2 for password-based key derivation.
 - **IVs must be unique**: never reuse an IV with the same key. Prefer default CBC or `encryptWithIV()` to generate one for each call. Transmit and store the IV with the ciphertext; the IV can be public.
 
-## Quick start
+### Quick start
 
 ```ts
 import { crypto } from '@h-ai/crypto'
 
 // 初始化（使用前必须调用）
-await crypto.init()
+const initialized = await crypto.init()
+if (!initialized.success)
+  throw new Error(initialized.error.message)
 ```
 
-### Asymmetric cryptography (encryption / signing)
+#### Asymmetric cryptography (encryption / signing)
 
 ```ts
 // 生成密钥对
@@ -61,7 +67,7 @@ crypto.asymmetric.isValidPublicKey(publicKey) // true
 crypto.asymmetric.isValidPrivateKey(privateKey) // true
 ```
 
-### Hashing (Hash / HMAC / verification)
+#### Hashing (Hash / HMAC / verification)
 
 ```ts
 // 字符串哈希
@@ -85,7 +91,7 @@ if (hash.success) {
 }
 ```
 
-### Symmetric encryption (default CBC / structured payload)
+#### Symmetric encryption (default CBC / structured payload)
 
 ```ts
 // 生成随机密钥和 IV
@@ -130,7 +136,7 @@ crypto.symmetric.isValidKey(key) // true
 crypto.symmetric.isValidIV(iv) // true
 ```
 
-### Password hashing (salted iterations)
+#### Password hashing (salted iterations)
 
 ```ts
 // 哈希密码（输出格式: $hai$<iterations>$<salt>$<hash>）
@@ -152,7 +158,7 @@ if (hashed.success) {
 }
 ```
 
-### Transport encryption (crypto.transport)
+#### Transport encryption (crypto.transport)
 
 The `crypto.transport` namespace provides transport encryption, allowing `@h-ai/serv`, `@h-ai/kit`, and `@h-ai/api-client` to share protocol constants and payload formats.
 
@@ -163,7 +169,7 @@ For typical applications, use the higher-level integrations:
 
 Call `crypto.transport.createServer()` / `createClient()` directly only for custom runtimes, tests, or manually integrated HTTP key exchange endpoints.
 
-#### Workflow
+##### Workflow
 
 1. Call `await crypto.init()` to initialize `crypto.asymmetric` and `crypto.symmetric`.
 2. On the server, create a `manager` with `crypto.transport.createServer()`. It holds the server key pair and stores client public keys. Inject a shared `keyStore` for multi-node deployments.
@@ -217,14 +223,14 @@ if (!server.success)
 
 Access protocol constants through `crypto.transport.protocol` (or `TRANSPORT_PROTOCOL`): `X-Client-Id`, `X-Encrypted`, and the default `/_hai/key-exchange`.
 
-### Close the module
+#### Close the module
 
 ```ts
 // 使用完毕后关闭，释放内部状态
 await crypto.close()
 ```
 
-## Error handling
+### Error handling
 
 All operations return `HaiResult<T>`:
 
@@ -235,7 +241,11 @@ if (!result.success) {
 }
 ```
 
-## Tests
+### Optional integrations
+
+The admin console's online encryption demo calls the Crypto SM3/SM4 APIs directly. SM4 uses a random temporary key and IV and verifies decryption before showing success; keys are not saved. Changing input clears previous results. Random digests or Base64 must not be presented as cryptographic results.
+
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/crypto test
@@ -244,5 +254,3 @@ pnpm --filter @h-ai/crypto test
 ## License
 
 Apache-2.0
-
-The admin console's online encryption demo calls the Crypto SM3/SM4 APIs directly. SM4 uses a random temporary key and IV and verifies decryption before showing success; keys are not saved. Changing input clears previous results. Random digests or Base64 must not be presented as cryptographic results.

package/README.ja.md

@@ -4,6 +4,8 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/cache](../cache/README.ja.md) · [@h-ai/core](../core/README.ja.md) · [@h-ai/reldb](../reldb/README.ja.md)
 
+## 概要
+
 非対称暗号、ハッシュ、対称暗号、パスワードハッシュを提供する暗号モジュールです。
 
 ## 主な機能
@@ -15,22 +17,26 @@
 - 通信暗号化（`crypto.transport`：サーバー管理機能 + クライアントの `encryptedFetch`）
 - サーバー・ブラウザー共通（Node.js / ブラウザー）
 
-## セキュリティに関する注意
+## 使い始める
+
+### セキュリティに関する注意
 
 - **SM4 の既定の暗号化結果は構造化された暗号文**：`crypto.symmetric.encrypt(data, key)` は既定で CBC + ランダム IV を使用し、`{ mode, ciphertext, iv, encoding }` を返します。復号時はこのオブジェクトを `crypto.symmetric.decrypt(payload, key)` に渡します。
 - **SM4 の `deriveKey(password, salt)` は KDF ではありません**：SM3 を 1 回実行するだけで、パスワードの総当たり攻撃への耐性はありません。**パスワード保存には使用禁止**です。パスワードハッシュには `crypto.password.hash(password)`、パスワードからの鍵導出には PBKDF2 / scrypt / Argon2 を使用してください。
 - **IV は毎回一意にしてください**：同じ鍵で IV を再利用してはいけません。既定の CBC または `encryptWithIV()` による毎回の自動生成を推奨します。IV は暗号文と一緒に送信・保存します（公開可能で、秘密にする必要はありません）。
 
-## クイックスタート
+### クイックスタート
 
 ```ts
 import { crypto } from '@h-ai/crypto'
 
 // 初始化（使用前必须调用）
-await crypto.init()
+const initialized = await crypto.init()
+if (!initialized.success)
+  throw new Error(initialized.error.message)
 ```
 
-### 非対称暗号（暗号化・復号 / 署名・検証）
+#### 非対称暗号（暗号化・復号 / 署名・検証）
 
 ```ts
 // 生成密钥对
@@ -61,7 +67,7 @@ crypto.asymmetric.isValidPublicKey(publicKey) // true
 crypto.asymmetric.isValidPrivateKey(privateKey) // true
 ```
 
-### ハッシュ（Hash / HMAC / 検証）
+#### ハッシュ（Hash / HMAC / 検証）
 
 ```ts
 // 字符串哈希
@@ -85,7 +91,7 @@ if (hash.success) {
 }
 ```
 
-### 対称暗号（既定の CBC / 構造化暗号文）
+#### 対称暗号（既定の CBC / 構造化暗号文）
 
 ```ts
 // 生成随机密钥和 IV
@@ -130,7 +136,7 @@ crypto.symmetric.isValidKey(key) // true
 crypto.symmetric.isValidIV(iv) // true
 ```
 
-### パスワードハッシュ（ソルト付き反復）
+#### パスワードハッシュ（ソルト付き反復）
 
 ```ts
 // 哈希密码（输出格式: $hai$<iterations>$<salt>$<hash>）
@@ -152,7 +158,7 @@ if (hashed.success) {
 }
 ```
 
-### 通信暗号化（crypto.transport）
+#### 通信暗号化（crypto.transport）
 
 通信暗号化は `crypto.transport` 名前空間で提供し、`@h-ai/serv`、`@h-ai/kit`、`@h-ai/api-client` で同じプロトコル定数とペイロード形式を再利用します。
 
@@ -163,7 +169,7 @@ if (hashed.success) {
 
 `crypto.transport.createServer()` / `createClient()` の直接呼び出しは、独自ランタイム、テスト、HTTP 鍵交換 endpoint を自分で接続する場合に限って推奨します。
 
-#### 使用手順
+##### 使用手順
 
 1. `await crypto.init()` を呼び、`crypto.asymmetric` と `crypto.symmetric` を初期化します。
 2. サーバーで `crypto.transport.createServer()` を呼び、`manager` を作成します。サーバー鍵ペアとクライアント公開鍵を管理します。複数ノードでは共有 `keyStore` を注入できます。
@@ -217,14 +223,14 @@ if (!server.success)
 
 プロトコル定数は `crypto.transport.protocol`（または `TRANSPORT_PROTOCOL`）で取得できます：`X-Client-Id`、`X-Encrypted`、既定の `/_hai/key-exchange`。
 
-### モジュールの終了
+#### モジュールの終了
 
 ```ts
 // 使用完毕后关闭，释放内部状态
 await crypto.close()
 ```
 
-## エラー処理
+### エラー処理
 
 すべての操作は `HaiResult<T>` を返します：
 
@@ -235,14 +241,16 @@ if (!result.success) {
 }
 ```
 
-## テスト
+### 任意の連携
+
+管理画面のオンライン暗号化デモは Crypto の SM3/SM4 API を直接呼びます。SM4 はランダムな一時鍵と IV を使い、成功表示前に復号を検証します。鍵は保存しません。入力が変わると古い結果を消去し、ランダムなダイジェストや Base64 を暗号処理の結果として表示してはいけません。
+
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/crypto test
 ```
 
-## License
+## ライセンス
 
 Apache-2.0
-
-管理画面のオンライン暗号化デモは Crypto の SM3/SM4 API を直接呼びます。SM4 はランダムな一時鍵と IV を使い、成功表示前に復号を検証します。鍵は保存しません。入力が変わると古い結果を消去し、ランダムなダイジェストや Base64 を暗号処理の結果として表示してはいけません。

package/README.md

@@ -4,33 +4,39 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/cache](../cache/README.md) · [@h-ai/core](../core/README.md) · [@h-ai/reldb](../reldb/README.md)
 
+## 简介
+
 加密模块，提供非对称加密、哈希、对称加密与密码哈希能力。
 
-## 支持的能力
+## 核心功能清单
 
 - 非对称加密（密钥生成、加解密、签名验签）
 - 哈希（哈希、HMAC、验证）
 - 对称加密（ECB/CBC 模式）
 - 密码哈希（加盐迭代哈希）
 - 传输加密（`crypto.transport`：服务端管理器 + 客户端 `encryptedFetch`）
-- 前后端通用（Node.js / 浏览器）
+- SM2/SM3/SM4 与传输支持 Node.js / 浏览器；密码哈希仅服务端
+
+## 使用入门
 
-## 安全声明
+### 安全声明
 
 - **SM4 默认加密返回结构化密文**：`crypto.symmetric.encrypt(data, key)` 默认使用 CBC + 随机 IV，返回 `{ mode, ciphertext, iv, encoding }`；解密时把该对象传给 `crypto.symmetric.decrypt(payload, key)`。
 - **SM4 `deriveKey(password, salt)` 不是 KDF**：仅为单次 SM3 哈希，不具备密码爆破抗性，**禁止用于密码存储**。如需密码哈希，使用 `crypto.password.hash(password)`；如需从密码派生密钥，请采用 PBKDF2 / scrypt / Argon2。
 - **IV 必须唯一**：相同密钥下禁止复用 IV；推荐使用默认 CBC 或 `encryptWithIV()` 每次自动生成。密文与 IV 需一同传输与存储（IV 可公开，不必保密）。
 
-## 快速开始
+### 快速开始
 
 ```ts
 import { crypto } from '@h-ai/crypto'
 
 // 初始化（使用前必须调用）
-await crypto.init()
+const initialized = await crypto.init()
+if (!initialized.success)
+  throw new Error(initialized.error.message)
 ```
 
-### 非对称加密（加解密 / 签名验签）
+#### 非对称加密（加解密 / 签名验签）
 
 ```ts
 // 生成密钥对
@@ -61,7 +67,7 @@ crypto.asymmetric.isValidPublicKey(publicKey) // true
 crypto.asymmetric.isValidPrivateKey(privateKey) // true
 ```
 
-### 哈希（Hash / HMAC / 验证）
+#### 哈希（Hash / HMAC / 验证）
 
 ```ts
 // 字符串哈希
@@ -85,7 +91,7 @@ if (hash.success) {
 }
 ```
 
-### 对称加密（CBC 默认 / 结构化密文）
+#### 对称加密（CBC 默认 / 结构化密文）
 
 ```ts
 // 生成随机密钥和 IV
@@ -130,7 +136,7 @@ crypto.symmetric.isValidKey(key) // true
 crypto.symmetric.isValidIV(iv) // true
 ```
 
-### 密码哈希（加盐迭代）
+#### 密码哈希（加盐迭代）
 
 ```ts
 // 哈希密码（输出格式: $hai$<iterations>$<salt>$<hash>）
@@ -152,7 +158,7 @@ if (hashed.success) {
 }
 ```
 
-### 传输加密（crypto.transport）
+#### 传输加密（crypto.transport）
 
 传输加密统一通过 `crypto.transport` 命名空间提供，供 `@h-ai/serv`、`@h-ai/kit` 与 `@h-ai/api-client` 复用同一套协议常量和载荷格式。
 
@@ -163,7 +169,7 @@ if (hashed.success) {
 
 只有在自定义运行时、测试或你确实要自己接 HTTP 协商端点时，才建议直接调用 `crypto.transport.createServer()` / `createClient()`。
 
-#### 使用流程
+##### 使用流程
 
 1. 先 `await crypto.init()`，确保 `crypto.asymmetric` 与 `crypto.symmetric` 已初始化。
 2. 服务端调用 `crypto.transport.createServer()` 创建 `manager`；它持有服务端密钥对，并负责保存客户端公钥。多节点部署时可注入共享 `keyStore`。
@@ -217,14 +223,14 @@ if (!server.success)
 
 协议常量通过 `crypto.transport.protocol`（或 `TRANSPORT_PROTOCOL`）访问：`X-Client-Id`、`X-Encrypted`、默认 `/_hai/key-exchange`。
 
-### 关闭模块
+#### 关闭模块
 
 ```ts
 // 使用完毕后关闭，释放内部状态
 await crypto.close()
 ```
 
-## 错误处理
+### 错误处理
 
 所有操作返回 `HaiResult<T>`：
 
@@ -235,14 +241,16 @@ if (!result.success) {
 }
 ```
 
-## 测试
+### 可选集成
+
+管理端在线加密演示直接调用 Crypto SM3/SM4 API，SM4 使用随机临时密钥和 IV，并在显示成功前解密校验；密钥不保存。输入改变即清空旧结果，禁止用随机摘要或 Base64 伪装算法结果。
+
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/crypto test
 ```
 
-## License
+## 许可证
 
 Apache-2.0
-
-管理端在线加密演示直接调用 Crypto SM3/SM4 API，SM4 使用随机临时密钥和 IV，并在显示成功前解密校验；密钥不保存。输入改变即清空旧结果，禁止用随机摘要或 Base64 伪装算法结果。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/crypto",
   "type": "module",
-  "version": "0.1.0-alpha.65",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework cryptography module (asymmetric, symmetric, and hash).",
   "license": "Apache-2.0",
   "exports": {
@@ -23,12 +23,12 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.65",
+    "@h-ai/core": "0.1.0-alpha.67",
     "sm-crypto": "^0.5.7"
   },
   "optionalDependencies": {
-    "@h-ai/cache": "0.1.0-alpha.65",
-    "@h-ai/reldb": "0.1.0-alpha.65"
+    "@h-ai/cache": "0.1.0-alpha.67",
+    "@h-ai/reldb": "0.1.0-alpha.67"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",