@sparta-utils/crypto-util/README.md

一个支持多种加密算法的加密工具库，涵盖 AES、RSA、SM2、SM3、SM4、SHA、HMAC、MD5、Base64、JWT 等，适用于日常加解密、签名验签、摘要、Token 管理等场景。

# @sparta-utils/crypto-util

🚀 一个统一的加密解密工具库，支持常见加密算法（AES、RSA、SHA、MD5、HMAC、Base64、JWT）以及国密算法（SM2、SM3、SM4）。

- ✅ AES
- ✅ RSA
- ✅ SM2 / SM3 / SM4 (国密)
- ✅ SHA256 / SHA512
- ✅ HMAC
- ✅ MD5
- ✅ Base64 encode/decode
- ✅ JWT (sign/verify/decode)

## 📦 安装

```bash
npm install @sparta-utils/crypto-util

或者使用 yarn：

yarn add @sparta-utils/crypto-util
```

## 🔰 快速使用
```ts
import { CryptoUtil } from '@sparta-utils/crypto-util';

// ✅ AES 加密解密
import { CryptoUtil } from '@sparta-utils/crypto-util'

const key = '1234567890abcdef'
const iv = 'abcdef1234567890' // 可选，如果使用 ECB 模式可以不传

const encrypted = CryptoUtil.aes.encrypt('Hello AES', {
  key,
  iv,
  mode: 'cbc'
})
console.log('加密后:', encrypted)

const decrypted = CryptoUtil.aes.decrypt(encrypted, {
  key,
  iv,
  mode: 'cbc'
})

console.log('解密后:', decrypted)

// ✅ RSA 密钥生成、加密解密、签名验签
const { publicKey: rsaPub, privateKey: rsaPriv } = CryptoUtil.rsa.generateKeyPair();
const rsaEncrypted = CryptoUtil.rsa.encrypt('Hello RSA', rsaPub);
const rsaDecrypted = CryptoUtil.rsa.decrypt(rsaEncrypted, rsaPriv);
const rsaSignature = CryptoUtil.rsa.sign('RSA Message', rsaPriv);
const rsaVerified = CryptoUtil.rsa.verify('RSA Message', rsaSignature, rsaPub);
console.log('RSA验签:', rsaVerified);

// ✅ SM2 密钥生成、加密解密、签名验签
const { publicKey: rsaPub, privateKey: rsaPriv } = CryptoUtil.rsa.generateKeyPair()
console.log('RSA公钥:', rsaPub)
console.log('RSA私钥:', rsaPriv)
const rsaEncrypted = CryptoUtil.rsa.encrypt('Hello RSA', rsaPub)
console.log('RSA加密:', rsaEncrypted)
const rsaDecrypted = CryptoUtil.rsa.decrypt(rsaEncrypted, rsaPriv)
console.log('RSA解密:', rsaDecrypted)
const rsaSignature = CryptoUtil.rsa.sign('RSA Message', rsaPriv)
console.log('RSA签名:', rsaSignature)
const rsaVerified = CryptoUtil.rsa.verify('RSA Message', rsaSignature, rsaPub)
console.log('RSA验签结果:', rsaVerified)

// ✅ SM3 摘要
const sm3Hash = CryptoUtil.sm3('Hello SM3')
console.log('SM3摘要:', sm3Hash)

// ✅ SM4 加密解密
const sm4Key = '0123456789abcdef'; // 16字节密钥
const sm4Encrypted = CryptoUtil.sm4.encrypt('Hello SM4', sm4Key);
const sm4Decrypted = CryptoUtil.sm4.decrypt(sm4Encrypted, sm4Key);
console.log('SM4解密:', sm4Decrypted);

// ✅ SHA256 / SHA512
const sha256Hash = CryptoUtil.sha.sha256('Hello SHA256');
const sha512Hash = CryptoUtil.sha.sha512('Hello SHA512');
console.log('SHA256:', sha256Hash);
console.log('SHA512:', sha512Hash);

// ✅ HMAC-SHA
const hmac256 = CryptoUtil.hmac.hmac('sha256', 'hmacKey', 'HMAC Message')
const hmac512 = CryptoUtil.hmac.hmac('sha512', 'hmacKey', 'HMAC Message')

console.log('HMAC-SHA256:', hmac256)
console.log('HMAC-SHA512:', hmac512)

// ✅ MD5
const md5Hash = CryptoUtil.md5('Hello MD5');
console.log('MD5:', md5Hash);

// ✅ Base64
const base64Encoded = CryptoUtil.base64.encode('Hello Base64')
console.log('Base64编码:', base64Encoded)
const base64Decoded = CryptoUtil.base64.decode(base64Encoded)
console.log('Base64解码:', base64Decoded)

// ✅ JWT 签发与验证 浏览器不可使用 / 当前方法尚不完善
const jwtToken = CryptoUtil.jwt.sign({ uid: 1001 }, 'jwtSecretKey');
const jwtPayload = CryptoUtil.jwt.verify(jwtToken, 'jwtSecretKey');
console.log('JWT验证:', jwtPayload);
```

## 📚 支持功能
| 模块     | 功能                | 方法示例                                                      |
| ------ | ----------------- | --------------------------------------------------------- |
| AES    | 对称加密              | `encrypt`, `decrypt`                                      |
| RSA    | 非对称加密/签名          | `generateKeyPair`, `encrypt`, `decrypt`, `sign`, `verify` |
| SM2    | 国密加密/签名           | `generateKeyPair`, `encrypt`, `decrypt`, `sign`, `verify` |
| SM3    | 国密摘要算法            | `sm3(message)`                                            |
| SM4    | 国密对称加密            | `encrypt`, `decrypt`                                      |
| SHA    | 摘要（sha256、sha512） | `sha256`, `sha512`                                        |
| HMAC   | 带密钥摘要（HMAC-SHA）   | `hmacSHA256`, `hmacSHA512`                                |
| MD5    | MD5 哈希            | `md5(message)`                                            |
| Base64 | 编码与解码             | `encode`, `decode`                                        |
| JWT    | Token 生成与校验       | `sign`, `verify`, `decode`                                |

## 🧪 加密方法详解
# 🔐 AES (对称加密)
| 方法      | 说明    | 参数说明                                          |
| ------- | ----- | --------------------------------------------- |
| encrypt | 加密字符串 | `(text: string, key: string) => string`       |
| decrypt | 解密字符串 | `(cipherText: string, key: string) => string` |

# 🔑 RSA (非对称加密)
| 方法              | 说明     | 参数说明                                                              |
| --------------- | ------ | ----------------------------------------------------------------- |
| generateKeyPair | 生成密钥对  | `() => { publicKey: string, privateKey: string }`                 |
| encrypt         | 公钥加密   | `(text: string, publicKey: string) => string`                     |
| decrypt         | 私钥解密   | `(cipherText: string, privateKey: string) => string`              |
| sign            | 私钥签名   | `(text: string, privateKey: string) => string`                    |
| verify          | 公钥验证签名 | `(text: string, signature: string, publicKey: string) => boolean` |

# 🧧 SM2 (国密非对称加密)
| 方法              | 说明    | 参数说明                                                              |
| --------------- | ----- | ----------------------------------------------------------------- |
| generateKeyPair | 生成密钥对 | `() => { publicKey: string, privateKey: string }`                 |
| encrypt         | 公钥加密  | `(text: string, publicKey: string) => string`                     |
| decrypt         | 私钥解密  | `(cipherText: string, privateKey: string) => string`              |
| sign            | 签名    | `(text: string, privateKey: string) => string`                    |
| verify          | 验签    | `(text: string, signature: string, publicKey: string) => boolean` |

# 🧮 SM3 (国密摘要)
| 方法  | 说明   | 参数说明                       |
| --- | ---- | -------------------------- |
| sm3 | 生成摘要 | `(text: string) => string` |


# 🔒 SM4 (对称加密)
| 方法      | 说明 | 参数说明                                          |
| ------- | -- | --------------------------------------------- |
| encrypt | 加密 | `(text: string, key: string) => string`       |
| decrypt | 解密 | `(cipherText: string, key: string) => string` |


# 📌 SHA 摘要算法
| 方法     | 说明        | 参数说明                       |
| ------ | --------- | -------------------------- |
| sha256 | SHA256 哈希 | `(text: string) => string` |
| sha512 | SHA512 哈希 | `(text: string) => string` |


# 🔐 HMAC 加密（带密钥的哈希）
| 方法         | 说明          | 参数说明                                    |
| ---------- | ----------- | --------------------------------------- |
| hmacSHA256 | SHA256 HMAC | `(text: string, key: string) => string` |
| hmacSHA512 | SHA512 HMAC | `(text: string, key: string) => string` |


# 🧬 MD5
| 方法  | 说明     | 参数说明                       |
| --- | ------ | -------------------------- |
| md5 | MD5 哈希 | `(text: string) => string` |


# 🔤 Base64
| 方法     | 说明        | 参数说明                         |
| ------ | --------- | ---------------------------- |
| encode | Base64 编码 | `(text: string) => string`   |
| decode | Base64 解码 | `(base64: string) => string` |


# 🔑 JWT (JSON Web Token)
| 方法     | 说明           | 参数说明                                                                 |
| ------ | ------------ | -------------------------------------------------------------------- |
| sign   | 生成 token     | `(payload: object, secret: string, options?: SignOptions) => string` |
| verify | 验证 token 有效性 | `(token: string, secret: string) => object \| string`                |
| decode | 解码 token     | `(token: string) => null \| { [key: string]: any }`                  |


📄 License
MIT License © 2025-present