alejandrorodrom/encloom

GitHub: alejandrorodrom/encloom

一个基于 TypeScript/JavaScript 的轻量级密码学工具包,提供哈希、签名、密钥协商与加密等核心能力,解决前端与 Node.js 环境中的安全操作需求。

Stars: 0 | Forks: 0

# encloom [![npm version](https://img.shields.io/npm/v/encloom.svg)](https://www.npmjs.com/package/encloom) [![npm downloads](https://img.shields.io/npm/dm/encloom.svg)](https://www.npmjs.com/package/encloom) [![minified](https://img.shields.io/bundlephobia/min/encloom?label=minified&style=flat)](https://bundlephobia.com/package/encloom) [![minified + gzip](https://img.shields.io/bundlephobia/minzip/encloom?label=minified%20%2B%20gzip&style=flat)](https://bundlephobia.com/package/encloom) [![tree shaking](https://img.shields.io/badge/tree%20shaking-supported-brightgreen?style=flat)](https://bundlephobia.com/package/encloom) [![install size](https://packagephobia.com/badge?p=encloom)](https://packagephobia.com/result?p=encloom) [![License: MIT](https://img.shields.io/npm/l/encloom.svg)](https://github.com/alejandrorodrom/encloom/blob/main/LICENSE) [![GitHub stars](https://img.shields.io/github/stars/alejandrorodrom/encloom.svg)](https://github.com/alejandrorodrom/encloom/stargazers) [![CI](https://static.pigsec.cn/wp-content/uploads/repos/2026/04/770baeda8e195041.svg)](https://github.com/alejandrorodrom/encloom/actions/workflows/ci.yml) [![npm audit](https://static.pigsec.cn/wp-content/uploads/repos/2026/04/d7caad5940195042.svg)](https://github.com/alejandrorodrom/encloom/actions/workflows/npm-audit.yml) [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Node](https://img.shields.io/badge/node-%3E%3D20.19.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)

安装

``` npm install encloom ```

概述

子路径入口点:`encloom/`。软件包根目录 **`encloom`** 会重新导出相同的符号。参数和结果使用 **`Uint8Array`**。**ECDSA** `sign` / `verify` 期望的是**消息摘要**(例如 SHA-256 输出),而不是原始明文。

目录

- [安装](#sec-installation) - [概述](#sec-description) - [快速参考](#sec-reference) - [导入](#sec-imports) - [模块文档](#sec-documentation) - [`encloom`](#sec-imports)(软件包根目录) - [`encloom/random`](#mod-encloom-random) - [`encloom/sha2`](#mod-encloom-sha2) - [`encloom/sha3`](#mod-encloom-sha3) - [`encloom/hmac`](#mod-encloom-hmac) - [`encloom/aes`](#mod-encloom-aes) - [`encloom/ecdsa`](#mod-encloom-ecdsa) - [`encloom/ecdh`](#mod-encloom-ecdh) - [`encloom/ecies`](#mod-encloom-ecies) - [`encloom/pbkdf2`](#mod-encloom-pbkdf2) - [`encloom/constants`](#mod-encloom-constants) - [`encloom/helpers`](#mod-encloom-helpers) - [`helpers/encoding`](#mod-helpers-encoding) - [`helpers/validators`](#mod-helpers-validators) - [`helpers/util`](#mod-helpers-util) - [`helpers/types`](#mod-helpers-types)

快速参考

按导入路径导出的符号(类型仅在编译时生效)。第一列 → [模块文档](#sec-documentation)。 | 导入路径 | 导出 | |----------|------| | [`encloom`](#sec-imports) | 完整的公共 API(子路径的聚合)。 | | [`encloom/random`](#mod-encloom-random) | `randomBytes` | | [`encloom/sha2`](#mod-encloom-sha2) | `sha256`, `sha256Sync`, `sha512`, `sha512Sync`, `ripemd160`, `ripemd160Sync` | | [`encloom/sha3`](#mod-encloom-sha3) | `sha3`, `keccak256` | | [`encloom/hmac`](#mod-encloom-hmac) | `hmacSha256Sign`, `hmacSha256SignSync`, `hmacSha256Verify`, `hmacSha256VerifySync`, `hmacSha512Sign`, `hmacSha512SignSync`, `hmacSha512Verify`, `hmacSha512VerifySync` | | [`encloom/aes`](#mod-encloom-aes) | `aesCbcEncrypt`, `aesCbcDecrypt`, `aesCbcEncryptSync`, `aesCbcDecryptSync` | | [`encloom/ecdsa`](#mod-encloom-ecdsa) | `generatePrivate`, `generateKeyPair`, `getPublic`, `getPublicCompressed`, `compress`, `decompress`, `signatureExport`, `sign`, `recover`, `verify` | | [`encloom/ecdh`](#mod-encloom-ecdh) | `derive` | | [`encloom/ecies`](#mod-encloom-ecies) | `encrypt`, `decrypt`, `encryptSync`, `decryptSync`, `serialize`, `deserialize` | | [`encloom/pbkdf2`](#mod-encloom-pbkdf2) | `pbkdf2` | | [`encloom/constants`](#mod-encloom-constants) | 常量标识符:[完整列表](#mod-constants-list) | | [`encloom/helpers`](#mod-encloom-helpers) | `encoding`, `validators`, `util`, `types` | | [`encloom/helpers/encoding`](#mod-helpers-encoding) | `utf8ToBuffer`, `bufferToUtf8`, `concatBuffers`, `bufferToHex`, `hexToBuffer`, `sanitizeHex`, `removeHexLeadingZeros`, `hexToNumber` | | [`encloom/helpers/validators`](#mod-helpers-validators) | `assert`, `isScalar`, `isValidPrivateKey`, `equalConstTime`, `isValidKeyLength`, `checkPrivateKey`, `checkPublicKey`, `checkMessage` | | [`encloom/helpers/util`](#mod-helpers-util) | `isCompressed`, `isDecompressed`, `isPrefixed`, `sanitizePublicKey`, `exportRecoveryParam`, `importRecoveryParam`, `splitSignature`, `joinSignature`, `isValidDERSignature`, `sanitizeRSVSignature`; `SignResult` 接口 | | [`encloom/helpers/types`](#mod-helpers-types) | 类型:`Encrypted`, `PreEncryptOpts`, `KeyPair`, `Signature`, `Pbkdf2Digest`, `Pbkdf2Options`, `Pbkdf2Result` |

导出的常量

`HEX_ENC`, `UTF8_ENC`, `ENCRYPT_OP`, `DECRYPT_OP`, `SIGN_OP`, `VERIFY_OP`, `LENGTH_0`, `LENGTH_1`, `LENGTH_16`, `LENGTH_32`, `LENGTH_64`, `LENGTH_128`, `LENGTH_256`, `LENGTH_512`, `LENGTH_1024`, `AES_LENGTH`, `HMAC_LENGTH`, `AES_BROWSER_ALGO`, `HMAC_BROWSER_ALGO`, `HMAC_BROWSER`, `SHA256_BROWSER_ALGO`, `SHA512_BROWSER_ALGO`, `AES_NODE_ALGO`, `HMAC_NODE_ALGO`, `SHA256_NODE_ALGO`, `SHA512_NODE_ALGO`, `RIPEMD160_NODE_ALGO`, `PBKDF2_DIGEST_SHA256`, `PBKDF2_DIGEST_SHA512`, `PREFIX_LENGTH`, `KEY_LENGTH`, `IV_LENGTH`, `MAC_LENGTH`, `DECOMPRESSED_LENGTH`, `PREFIXED_KEY_LENGTH`, `PREFIXED_DECOMPRESSED_LENGTH`, `ECIES_SERIALIZED_MIN_LENGTH`, `MAX_KEY_LENGTH`, `MAX_MSG_LENGTH`, `PBKDF2_DEFAULT_ITERATIONS`, `EMPTY_BUFFER`, `EC_GROUP_ORDER`, `ZERO32`, `ERROR_BAD_MAC`, `ERROR_BAD_SIGNATURE`, `ERROR_BAD_PRIVATE_KEY`, `ERROR_BAD_PUBLIC_KEY`, `ERROR_BAD_EPHEM_PRIVATE_KEY`, `_ECIES_SERIALIZED_LENGTH`, `ERROR_AES_IV_LENGTH`, `ERROR_AES_KEY_LENGTH`, `ERROR_EMPTY_MESSAGE`, `ERROR_MESSAGE_TOO_LONG`

导入

**ESM** ``` import { sign, encrypt } from "encloom"; import { sha256Sync } from "encloom/sha2"; import { hexToBuffer } from "encloom/helpers/encoding"; ``` **CommonJS** ``` const { sign } = require("encloom"); const { decrypt } = require("encloom/ecies"); ``` 允许的路径与 [快速参考](#sec-reference) 中的“导入路径”列匹配。

模块文档

encloom/random

**描述。** 密码学安全的随机八位字节。 | 函数 | 输入 | 输出 | |------|------|------| | `randomBytes` | `length`: 1…1024 的整数 | `Uint8Array` | **示例** ``` import { randomBytes } from "encloom/random"; const nonce = randomBytes(32); ```

encloom/sha2

**描述。** SHA-256、SHA-512 和 RIPEMD-160 摘要。每个算法都有异步和同步变体。 | 函数 | 输入 | 输出 | |------|------|------| | `sha256` / `sha256Sync` | `msg: Uint8Array` | `Uint8Array`(32 个八位字节) | | `sha512` / `sha512Sync` | `msg: Uint8Array` | `Uint8Array`(64 个八位字节) | | `ripemd160` / `ripemd160Sync` | `msg: Uint8Array` | `Uint8Array`(20 个八位字节) | **示例** ``` import { sha256Sync } from "encloom/sha2"; import { utf8ToBuffer } from "encloom/helpers/encoding"; const digest = sha256Sync(utf8ToBuffer("hello")); ```

encloom/sha3

**描述。** SHA3-256(FIPS)和 Keccak-256 摘要。 | 函数 | 输入 | 输出 | |------|------|------| | `sha3` | `msg: Uint8Array` | `Uint8Array` | | `keccak256` | `msg: Uint8Array` | `Uint8Array` | **示例** ``` import { keccak256 } from "encloom/sha3"; const h = keccak256(new Uint8Array([1, 2, 3])); ```

encloom/hmac

**描述。** HMAC-SHA-256 和 HMAC-SHA-512。`…Verify` / `…VerifySync` 返回 `boolean`。 | 函数 | 输入 | 输出 | |------|------|------| | `hmacSha256Sign` / `…Sync` | `key`, `msg`: `Uint8Array` | `Uint8Array` | | `hmacSha256Verify` / `…Sync` | `key`, `msg`, `sig` | `boolean` | | `hmacSha512Sign` / `…Sync` | `key`, `msg` | `Uint8Array` | | `hmacSha512Verify` / `…Sync` | `key`, `msg`, `sig` | `boolean` | **示例** ``` import { hmacSha256SignSync, hmacSha256VerifySync } from "encloom/hmac"; const tag = hmacSha256SignSync(key, message); const ok = hmacSha256VerifySync(key, message, tag); ```

encloom/aes

**描述。** **AES-256-CBC** 加密和解密,使用 PKCS#7 填充。密钥 **32** 个八位字节,初始化向量 **16** 个八位字节。 | 函数 | 输入 | 输出 | |------|------|------| | `aesCbcEncrypt` / `…Sync` | `iv`, `key`, `data` | 密文 | | `aesCbcDecrypt` / `…Sync` | `iv`, `key`, `data` | 明文 | **示例** ``` import { aesCbcEncrypt, aesCbcDecrypt } from "encloom/aes"; import { randomBytes } from "encloom/random"; const key = randomBytes(32); const iv = randomBytes(16); const ct = await aesCbcEncrypt(iv, key, new Uint8Array([1, 2, 3])); const pt = await aesCbcDecrypt(iv, key, ct); ```

encloom/ecdsa

**描述。** **ECDSA** 在 **secp256k1** 上的密钥和签名操作。公钥使用 **SEC1** 编码(压缩或未压缩)。 | 函数 | 摘要 | |------|------| | `generatePrivate` | 随机私钥(32 个八位字节)。 | | `generateKeyPair` | `{ privateKey, publicKey }`(未压缩公钥)。 | | `getPublic` / `getPublicCompressed` | 从私钥派生的公钥。 | | `compress` / `decompress` | SEC1 格式转换。 | | `sign` | 签名摘要;可选第三个参数 `rsvSig`(默认 `false`:64 个八位字节;`true`:65 个八位字节)。 | | `verify` | 有效签名:`void`;无效:抛出异常。 | | `recover` | 从 65 字节签名和摘要恢复公钥。 | | `signatureExport` | 将紧凑或恢复的签名转换为 DER 编码。 | **示例** ``` import { generateKeyPair, sign, verify } from "encloom/ecdsa"; import { sha256Sync } from "encloom/sha2"; import { utf8ToBuffer } from "encloom/helpers/encoding"; const pair = generateKeyPair(); const digest = sha256Sync(utf8ToBuffer("hello")); const sig = sign(pair.privateKey, digest); verify(pair.publicKey, digest, sig); ```

encloom/ecdh

**描述。** **ECDH** 在 secp256k1 上(32 字节共享密钥)。 | 函数 | 输入 | 输出 | |------|------|------| | `derive` | `privateKeyA`, `publicKeyB` | 32 字节 `Uint8Array` | **示例** ``` import { generateKeyPair } from "encloom/ecdsa"; import { derive } from "encloom/ecdh"; const a = generateKeyPair(); const b = generateKeyPair(); const shared = derive(a.privateKey, b.publicKey); ```

encloom/ecies

**描述。** **ECIES** 在 secp256k1 上:加密到接收方公钥;使用私钥解密。线性格式:`serialize` / `deserialize`。`encrypt` / `encryptSync` 接受可选的 `Partial`(`iv`、`ephemPrivateKey` 等)。 | 函数 | 摘要 | |------|------| | `encrypt` / `decrypt` | 异步。 | | `encryptSync` / `decryptSync` | 同步(`Uint8Array`,不是 `Promise`)。 | | `serialize` / `deserialize` | 对象 ↔ 字节。 | **示例** ``` import { generateKeyPair } from "encloom/ecdsa"; import { encrypt, decrypt, serialize, deserialize } from "encloom/ecies"; import { utf8ToBuffer, bufferToUtf8 } from "encloom/helpers/encoding"; const alice = generateKeyPair(); const msg = utf8ToBuffer("secret"); const enc = await encrypt(alice.publicKey, msg); const wire = serialize(enc); const out = await decrypt(alice.privateKey, deserialize(wire)); bufferToUtf8(out); ```

encloom/pbkdf2

**描述。** **PBKDF2**(HMAC-SHA-256 或 HMAC-SHA-512)。输出:32 字节 `key`、`salt`、`iterations`、`digest`。随机 16 字节 salt 和 `PBKDF2_DEFAULT_ITERATIONS`,除非在 `Pbkdf2Options` 中覆盖。 | 函数 | 输入 | 输出 | |------|------|------| | `pbkdf2` | `password`,可选的 `Pbkdf2Options` | `Promise` | **示例** ``` import { pbkdf2 } from "encloom/pbkdf2"; import { utf8ToBuffer } from "encloom/helpers/encoding"; const first = await pbkdf2(utf8ToBuffer("password")); const again = await pbkdf2(utf8ToBuffer("password"), { salt: first.salt, iterations: first.iterations, digest: first.digest, }); ```

encloom/constants

**描述。** 长度、算法名称、错误、曲线数据。无函数。[列表](#mod-constants-list)。 **示例** ``` import { KEY_LENGTH, MAX_MSG_LENGTH } from "encloom/constants"; ```

encloom/helpers

**描述。** 重新导出 `encoding`、`validators`、`util` 和 `types`。子路径(`helpers/encoding` 等)限制导入范围。

helpers/encoding

| 函数 | 摘要 | |------|------| | `utf8ToBuffer` / `bufferToUtf8` | UTF-8 编码和解码。 | | `concatBuffers` | 连接 `Uint8Array` 值。 | | `bufferToHex` | 小写十六进制字符串。 | | `hexToBuffer` | 解析十六进制(可选 `0x` 前)。 | | `sanitizeHex` | 去除 `0x` 前缀。 | | `removeHexLeadingZeros` | 规范化十六进制字符串。 | | `hexToNumber` | 十六进制字符串到整数。 | **示例** ``` import { hexToBuffer, bufferToHex } from "encloom/helpers/encoding"; bufferToHex(hexToBuffer("0xdead")); ```

helpers/validators

| 函数 | 摘要 | |------|------| | `assert` | 带有错误消息的布尔检查。 | | `isScalar` | 值是否为 32 字节 `Uint8Array`。 | | `isValidPrivateKey` | 私钥是否在曲线范围内。 | | `equalConstTime` | 八位字节序列的恒定时间相等性。 | | `isValidKeyLength` | 验证随机字节生成的长度。 | | `checkPrivateKey`, `checkPublicKey`, `checkMessage` | 严格验证;如果检查失败则抛出异常。 | **示例** ``` import { isValidPrivateKey } from "encloom/helpers/validators"; isValidPrivateKey(secretKeyBytes); ```

helpers/util

| 函数 | 摘要 | |------|------| | `isCompressed`, `isDecompressed`, `isPrefixed` | 公钥格式分类。 | | `sanitizePublicKey` | 如有需要添加 SEC1 前缀。 | | `exportRecoveryParam`, `importRecoveryParam` | 为签名映射恢复索引。 | | `splitSignature`, `joinSignature` | 拆分和连接 **r**、**s**、**v** 组件。 | | `isValidDERSignature` | 启发式 DER 签名检测。 | | `sanitizeRSVSignature` | 规范化 65 字节签名;返回 `SignResult`。 | **示例** ``` import { splitSignature } from "encloom/helpers/util"; const { r, s, v } = splitSignature(sig65Bytes); ```

helpers/types

**描述。** 仅类型模块:`Encrypted`, `PreEncryptOpts`, `KeyPair`, `Signature`, `Pbkdf2Digest`, `Pbkdf2Options`, `Pbkdf2Result`。 **示例** ``` import type { KeyPair, Encrypted, Pbkdf2Result } from "encloom/helpers/types"; ```
标签:AES-CBC, CMS安全, CVE, ECDH, ECDSA, ECIES, GNU通用公共许可证, HMAC, JavaScript, Keccak, MITM代理, Node.js, npm 包, PBKDF2, secp256k1, SHA-2, SHA-3, tree shaking, TypeScript, Uint8Array, Web Crypto, 前端加密, 加密工具包, 加密编码, 后端加密, 哈希算法, 子路径导出, 安全插件, 安全随机数, 密码学, 密钥交换, 密钥派生, 手动系统调用, 数字签名, 数据可视化, 自动化攻击