@h-ai/crypto 0.1.0-alpha5

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [idealworld.group]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,162 @@
+# @h-ai/crypto
+
+加密模块，提供非对称加密、哈希、对称加密与密码哈希能力。
+
+## 支持的能力
+
+- 非对称加密（密钥生成、加解密、签名验签）
+- 哈希（哈希、HMAC、验证）
+- 对称加密（ECB/CBC 模式）
+- 密码哈希（加盐迭代哈希）
+- 前后端通用（Node.js / 浏览器）
+
+## 快速开始
+
+```ts
+import { crypto } from '@h-ai/crypto'
+
+// 初始化（使用前必须调用）
+await crypto.init()
+```
+
+### 非对称加密（加解密 / 签名验签）
+
+```ts
+// 生成密钥对
+const keyPair = crypto.asymmetric.generateKeyPair()
+if (!keyPair.success)
+  throw new Error(keyPair.error.message)
+const { publicKey, privateKey } = keyPair.data
+
+// 加密 / 解密
+const encrypted = crypto.asymmetric.encrypt('Hello', publicKey)
+if (encrypted.success) {
+  const decrypted = crypto.asymmetric.decrypt(encrypted.data, privateKey)
+  // decrypted.data === 'Hello'
+}
+
+// 输出 base64 格式密文
+const b64 = crypto.asymmetric.encrypt('Hello', publicKey, { outputFormat: 'base64' })
+
+// 签名 / 验签
+const sig = crypto.asymmetric.sign('important data', privateKey)
+if (sig.success) {
+  const valid = crypto.asymmetric.verify('important data', sig.data, publicKey)
+  // valid.data === true
+}
+
+// 校验密钥格式
+crypto.asymmetric.isValidPublicKey(publicKey) // true
+crypto.asymmetric.isValidPrivateKey(privateKey) // true
+```
+
+### 哈希（Hash / HMAC / 验证）
+
+```ts
+// 字符串哈希
+const hash = crypto.hash.hash('Hello!')
+// hash.data → 64 字符十六进制哈希值
+
+// Uint8Array 输入
+const buf = new TextEncoder().encode('Hello!')
+const hashBuf = crypto.hash.hash(buf)
+
+// 十六进制编码输入
+const hashHex = crypto.hash.hash('48656c6c6f21', { inputEncoding: 'hex' })
+
+// HMAC
+const hmac = crypto.hash.hmac('message', 'secret-key')
+
+// 验证哈希是否匹配
+if (hash.success) {
+  const matched = crypto.hash.verify('Hello!', hash.data)
+  // matched.data === true
+}
+```
+
+### 对称加密（ECB / CBC）
+
+```ts
+// 生成随机密钥和 IV
+const key = crypto.symmetric.generateKey()
+const iv = crypto.symmetric.generateIV()
+
+// ECB 模式（默认）
+const ecbEnc = crypto.symmetric.encrypt('data', key)
+if (ecbEnc.success) {
+  const ecbDec = crypto.symmetric.decrypt(ecbEnc.data, key)
+  // ecbDec.data === 'data'
+}
+
+// CBC 模式（需指定 IV）
+const cbcEnc = crypto.symmetric.encrypt('data', key, { mode: 'cbc', iv })
+if (cbcEnc.success) {
+  const cbcDec = crypto.symmetric.decrypt(cbcEnc.data, key, { mode: 'cbc', iv })
+}
+
+// 快捷方式：自动生成 IV 的 CBC 加解密
+const withIV = crypto.symmetric.encryptWithIV('data', key)
+if (withIV.success) {
+  const dec = crypto.symmetric.decryptWithIV(withIV.data.ciphertext, key, withIV.data.iv)
+}
+
+// 输出 base64 格式
+const b64Enc = crypto.symmetric.encrypt('data', key, { outputFormat: 'base64' })
+
+// 从密码派生密钥
+const derivedKey = crypto.symmetric.deriveKey('my-password', 'random-salt')
+
+// 校验密钥/IV 格式
+crypto.symmetric.isValidKey(key) // true
+crypto.symmetric.isValidIV(iv) // true
+```
+
+### 密码哈希（加盐迭代）
+
+```ts
+// 哈希密码（输出格式: $hai$<iterations>$<salt>$<hash>）
+const hashed = crypto.password.hash('myPassword123')
+
+// 自定义盐值长度和迭代次数
+const custom = crypto.password.hash('myPassword123', {
+  saltLength: 32,
+  iterations: 20000,
+})
+
+// 验证密码
+if (hashed.success) {
+  const ok = crypto.password.verify('myPassword123', hashed.data)
+  // ok.data === true
+
+  const wrong = crypto.password.verify('wrongPassword', hashed.data)
+  // wrong.data === false
+}
+```
+
+### 关闭模块
+
+```ts
+// 使用完毕后关闭，释放内部状态
+await crypto.close()
+```
+
+## 错误处理
+
+所有操作返回 `HaiResult<T>`：
+
+```ts
+const result = crypto.asymmetric.encrypt('data', publicKey)
+if (!result.success) {
+  // result.error.code / result.error.message
+}
+```
+
+## 测试
+
+```bash
+pnpm --filter @h-ai/crypto test
+```
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,332 @@
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+
+declare const HaiCryptoError: {
+    readonly INVALID_INPUT: _h_ai_core.HaiErrorDef;
+    readonly INVALID_KEY: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly INIT_FAILED: _h_ai_core.HaiErrorDef;
+    readonly KEY_GENERATION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly ENCRYPTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly DECRYPTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly SIGN_FAILED: _h_ai_core.HaiErrorDef;
+    readonly VERIFY_FAILED: _h_ai_core.HaiErrorDef;
+    readonly HASH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly HMAC_FAILED: _h_ai_core.HaiErrorDef;
+    readonly INVALID_IV: _h_ai_core.HaiErrorDef;
+};
+/** 密文模式：0=C1C2C3（旧版），1=C1C3C2（国标） */
+type CipherMode = 0 | 1;
+/** 非对称密钥对 */
+interface KeyPair {
+    /** 公钥（十六进制字符串，包含 04 前缀为非压缩格式） */
+    publicKey: string;
+    /** 私钥（十六进制字符串，64 字符） */
+    privateKey: string;
+}
+/** 非对称加密选项 */
+interface AsymmetricEncryptOptions {
+    /** 密文模式：0=C1C2C3（旧版），1=C1C3C2（国标，默认） */
+    cipherMode?: CipherMode;
+    /** 输出格式 */
+    outputFormat?: 'hex' | 'base64';
+}
+/** 签名选项 */
+interface SignOptions {
+    /** 是否对数据进行哈希（默认 true） */
+    hash?: boolean;
+    /** 用户 ID（默认 "1234567812345678"） */
+    userId?: string;
+}
+/** 哈希选项 */
+interface HashOptions {
+    /** 输入编码 */
+    inputEncoding?: 'utf8' | 'hex';
+}
+/** 对称加密模式 */
+type SymmetricMode = 'ecb' | 'cbc';
+/** 对称加密选项 */
+interface SymmetricOptions {
+    /** 加密模式 */
+    mode?: SymmetricMode;
+    /** IV 向量（CBC 模式必需，32 个十六进制字符） */
+    iv?: string;
+    /** 输入编码 */
+    inputEncoding?: 'utf8' | 'hex';
+    /** 输出格式 */
+    outputFormat?: 'hex' | 'base64';
+}
+/** 带 IV 加密结果 */
+interface EncryptWithIVResult {
+    /** 密文 */
+    ciphertext: string;
+    /** IV 向量 */
+    iv: string;
+}
+/** 密码哈希配置 */
+interface PasswordConfig {
+    /** 盐值长度（默认 16） */
+    saltLength?: number;
+    /** 迭代次数（默认 10000） */
+    iterations?: number;
+}
+/**
+ * 非对称加密操作接口
+ *
+ * 通过 `crypto.asymmetric` 访问，需先调用 `crypto.init()`。
+ */
+interface AsymmetricOperations {
+    /**
+     * 生成密钥对
+     *
+     * @returns 成功时包含公私钥对；失败时返回 KEY_GENERATION_FAILED
+     */
+    generateKeyPair: () => HaiResult<KeyPair>;
+    /**
+     * 非对称加密
+     *
+     * @param data - 待加密明文
+     * @param publicKey - 公钥（十六进制，支持带/不带 04 前缀）
+     * @param options - 加密选项（密文模式、输出格式）
+     * @returns 成功时返回密文字符串；失败时返回 INVALID_KEY 或 ENCRYPTION_FAILED
+     */
+    encrypt: (data: string, publicKey: string, options?: AsymmetricEncryptOptions) => HaiResult<string>;
+    /**
+     * 非对称解密
+     *
+     * 自动检测 base64 格式输入并转换为 hex。
+     *
+     * @param ciphertext - 密文（hex 或 base64）
+     * @param privateKey - 私钥（64 字符十六进制）
+     * @param options - 解密选项（密文模式需与加密时一致）
+     * @returns 成功时返回明文；失败时返回 INVALID_KEY 或 DECRYPTION_FAILED
+     */
+    decrypt: (ciphertext: string, privateKey: string, options?: AsymmetricEncryptOptions) => HaiResult<string>;
+    /**
+     * 签名
+     *
+     * @param data - 待签名数据
+     * @param privateKey - 私钥（64 字符十六进制）
+     * @param options - 签名选项（hash 开关、userId）
+     * @returns 成功时返回签名字符串；失败时返回 INVALID_KEY 或 SIGN_FAILED
+     */
+    sign: (data: string, privateKey: string, options?: SignOptions) => HaiResult<string>;
+    /**
+     * 验签
+     *
+     * @param data - 原始数据
+     * @param signature - 签名（需与签名时使用相同的 hash/userId 选项）
+     * @param publicKey - 公钥（支持带/不带 04 前缀）
+     * @param options - 验签选项
+     * @returns 成功时返回 boolean；失败时返回 INVALID_KEY 或 VERIFY_FAILED
+     */
+    verify: (data: string, signature: string, publicKey: string, options?: SignOptions) => HaiResult<boolean>;
+    /**
+     * 校验公钥格式是否合法
+     *
+     * 合法格式：128 字符十六进制（无前缀）或 130 字符（含 04 前缀）。
+     */
+    isValidPublicKey: (key: string) => boolean;
+    /**
+     * 校验私钥格式是否合法
+     *
+     * 合法格式：64 字符十六进制。
+     */
+    isValidPrivateKey: (key: string) => boolean;
+}
+/**
+ * 哈希操作接口
+ *
+ * 通过 `crypto.hash` 访问，需先调用 `crypto.init()`。
+ */
+interface HashOperations {
+    /**
+     * 计算哈希
+     *
+     * @param data - 待哈希数据（字符串或 Uint8Array）
+     * @param options - 输入编码选项
+     * @returns 成功时返回 64 字符十六进制哈希值；失败时返回 HASH_FAILED
+     */
+    hash: (data: string | Uint8Array, options?: HashOptions) => HaiResult<string>;
+    /**
+     * 计算 HMAC
+     *
+     * 使用 HMAC 算法（RFC 2104）计算消息认证码。
+     * 当密钥长度超过块大小（64 字节）时，会先对密钥进行哈希。
+     *
+     * @param data - 待计算数据
+     * @param key - HMAC 密钥
+     * @returns 成功时返回 64 字符十六进制 HMAC 值；失败时返回 HMAC_FAILED
+     */
+    hmac: (data: string, key: string) => HaiResult<string>;
+    /**
+     * 验证数据的哈希是否匹配
+     *
+     * 比较时忽略大小写。
+     *
+     * @param data - 原始数据
+     * @param expectedHash - 期望的哈希值
+     * @returns 成功时返回 boolean；失败时返回 HASH_FAILED
+     */
+    verify: (data: string, expectedHash: string) => HaiResult<boolean>;
+}
+/**
+ * 对称加密操作接口
+ *
+ * 通过 `crypto.symmetric` 访问，需先调用 `crypto.init()`。
+ * 支持 ECB/CBC 两种模式，CBC 模式需要提供 IV。
+ */
+interface SymmetricOperations {
+    /** 生成随机密钥（16 字节 = 32 个十六进制字符） */
+    generateKey: () => string;
+    /** 生成随机 IV（16 字节 = 32 个十六进制字符） */
+    generateIV: () => string;
+    /**
+     * 对称加密
+     *
+     * @param data - 待加密明文
+     * @param key - 密钥（32 字符十六进制）
+     * @param options - 加密模式/IV/输出格式
+     * @returns 成功时返回密文；失败时返回 INVALID_KEY/INVALID_IV/ENCRYPTION_FAILED
+     */
+    encrypt: (data: string, key: string, options?: SymmetricOptions) => HaiResult<string>;
+    /**
+     * 对称解密
+     *
+     * 自动检测 base64 格式输入并转换为 hex。
+     *
+     * @param ciphertext - 密文（hex 或 base64）
+     * @param key - 密钥（32 字符十六进制）
+     * @param options - 解密模式/IV（需与加密时一致）
+     * @returns 成功时返回明文；失败时返回 INVALID_KEY/INVALID_IV/DECRYPTION_FAILED
+     */
+    decrypt: (ciphertext: string, key: string, options?: SymmetricOptions) => HaiResult<string>;
+    /**
+     * 带 IV 加密（CBC 模式，自动生成随机 IV）
+     *
+     * @param data - 待加密明文
+     * @param key - 密钥（32 字符十六进制）
+     * @returns 成功时返回 { ciphertext, iv }；失败时同 encrypt
+     */
+    encryptWithIV: (data: string, key: string) => HaiResult<EncryptWithIVResult>;
+    /**
+     * 带 IV 解密（CBC 模式）
+     *
+     * @param ciphertext - 密文
+     * @param key - 密钥
+     * @param iv - 加密时使用的 IV
+     * @returns 成功时返回明文；失败时同 decrypt
+     */
+    decryptWithIV: (ciphertext: string, key: string, iv: string) => HaiResult<string>;
+    /**
+     * 从密码和盐值派生密钥
+     *
+     * 内部使用哈希(password + salt) 取前 32 字符作为密钥。
+     * 注意：此为简单派生，不适用于高安全场景。
+     *
+     * @param password - 密码
+     * @param salt - 盐值
+     * @returns 32 字符十六进制密钥
+     */
+    deriveKey: (password: string, salt: string) => string;
+    /** 校验密钥格式是否合法（32 字符十六进制） */
+    isValidKey: (key: string) => boolean;
+    /** 校验 IV 格式是否合法（32 字符十六进制） */
+    isValidIV: (iv: string) => boolean;
+}
+/**
+ * 密码哈希操作接口
+ *
+ * 通过 `crypto.password` 访问，需先调用 `crypto.init()`。
+ * 使用迭代加盐的方式生成密码哈希。
+ */
+interface PasswordOperations {
+    /**
+     * 对密码进行哈希
+     *
+     * 输出格式: `$hai$<iterations>$<salt>$<hash>`
+     *
+     * @param password - 明文密码（不能为空）
+     * @param config - 可选配置（盐值长度、迭代次数）
+     * @returns 成功时返回格式化的哈希字符串；失败时返回 INVALID_INPUT 或 HASH_FAILED
+     */
+    hash: (password: string, config?: PasswordConfig) => HaiResult<string>;
+    /**
+     * 验证密码是否匹配
+     *
+     * 自动从哈希字符串中解析迭代次数和盐值进行重新计算。
+     *
+     * @param password - 待验证的明文密码
+     * @param hash - 存储的哈希值（格式: `$hai$<iterations>$<salt>$<hash>`）
+     * @returns 成功时返回 boolean；失败时返回 INVALID_INPUT 或 VERIFY_FAILED
+     */
+    verify: (password: string, hash: string) => HaiResult<boolean>;
+}
+/**
+ * 加密模块函数接口
+ *
+ * `crypto` 服务对象的类型定义。使用前必须调用 `init()` 初始化。
+ *
+ * @example
+ * ```ts
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * await crypto.init()
+ * const hash = crypto.hash.hash('hello')
+ * await crypto.close()
+ * ```
+ */
+interface CryptoFunctions {
+    /**
+     * 初始化加密模块
+     *
+     * 创建非对称/哈希/对称/密码哈希操作实例。
+     * 重复调用会先关闭再重新初始化。
+     *
+     * @returns 成功时返回 ok(undefined)；失败时返回 INIT_FAILED
+     */
+    init: () => Promise<HaiResult<void>>;
+    /**
+     * 关闭加密模块，释放内部状态
+     *
+     * 关闭后再访问 asymmetric/hash/symmetric/password 会返回 NOT_INITIALIZED 错误。
+     */
+    close: () => Promise<void>;
+    /** 是否已初始化 */
+    readonly isInitialized: boolean;
+    /** 非对称加密操作（未初始化时所有方法返回 NOT_INITIALIZED） */
+    readonly asymmetric: AsymmetricOperations;
+    /** 哈希操作（未初始化时所有方法返回 NOT_INITIALIZED） */
+    readonly hash: HashOperations;
+    /** 对称加密操作（未初始化时所有方法返回 NOT_INITIALIZED） */
+    readonly symmetric: SymmetricOperations;
+    /** 密码哈希操作（未初始化时所有方法返回 NOT_INITIALIZED） */
+    readonly password: PasswordOperations;
+}
+
+/**
+ * @h-ai/crypto — 加密服务主入口
+ *
+ * 提供统一的 `crypto` 对象，聚合所有结构化加密操作。
+ * @module crypto-main
+ */
+
+/**
+ * 加密模块服务对象（统一入口）
+ *
+ * 使用前必须调用 `crypto.init()` 进行初始化。
+ * 未初始化时访问 asymmetric/hash/symmetric/password 的任何方法均返回 NOT_INITIALIZED 错误。
+ *
+ * @example
+ * ```ts
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * await crypto.init()
+ * const hash = crypto.hash.hash('hello')
+ * const keyPair = crypto.asymmetric.generateKeyPair()
+ * await crypto.close()
+ * ```
+ */
+declare const crypto: CryptoFunctions;
+
+export { type AsymmetricEncryptOptions, type AsymmetricOperations, type CipherMode, type CryptoFunctions, type EncryptWithIVResult, HaiCryptoError, type HashOperations, type HashOptions, type KeyPair, type PasswordConfig, type PasswordOperations, type SignOptions, type SymmetricMode, type SymmetricOperations, type SymmetricOptions, crypto };