npm package: @lshch/okay-cipher
Description: Okay-Cipher is a very okay JavaScript cipher toolkit.
Author: lshch
Latest version: 0.0.1

# Okay-Cipher

[![NPM version](https://img.shields.io/npm/v/@lshch/okay-cipher.svg?style=flat-square)](https://www.npmjs.com/package/@lshch/okay-cipher)
[![NPM downloads](https://img.shields.io/npm/dm/@lshch/okay-cipher.svg?style=flat-square)](https://www.npmjs.com/package/@lshch/okay-cipher)

Okay-Cipher 是一个简单易用的 JavaScript 加密工具包，基于国密 SM4 算法，支持对象和基础值的加密/解密操作。

## 特性

- 🔐 基于国密 SM4 算法的安全加密
- 📦 支持 ESM 和 CJS 两种模块化格式
- 🎯 支持对象和基础值（字符串、数字）的加密/解密
- 🔄 自动密钥处理（通过 SM3 哈希算法将任意长度密钥转换为标准 16 字节 SM4 密钥）
- 📝 提供 TypeScript 类型定义
- 🧪 内置校验函数验证加密数据有效性

## 安装

```bash
npm install @lshch/okay-cipher
```

## 快速开始

### 在 Node.js 中使用

```javascript
import { encryptObject, decryptObject } from '@lshch/okay-cipher';

// 加密对象
const userData = { name: 'Alice', age: 30 };
const encrypted = encryptObject(userData, { key: 'your-secret-key' });
console.log('加密结果:', encrypted);
// 输出示例: "5a4e-b2c1-8f3d-9e2a-7c4b-1d3f-9a8b-2c4e"

// 解密对象
const decrypted = decryptObject(encrypted, { key: 'your-secret-key' });
console.log('解密结果:', decrypted);
// 输出: { name: 'Alice', age: 30 }
```

### 在浏览器中使用 (通过 script 标签)

Okay-Cipher 提供了 IIFE (Immediately Invoked Function Expression) 版本，可以直接在浏览器中通过 script 标签引入使用：

```html
<!DOCTYPE html>
<html>
<head>
    <title>Okay-Cipher Browser Demo</title>
</head>
<body>
    <script src="https://unpkg.com/@lshch/okay-cipher@latest/dist/okay-cipher.iife.js"></script>
    <script>
        // 使用全局变量 OkayCipher
        const { encryptObject, decryptObject } = window.OkayCipher;
        
        // 加密对象
        const userData = { name: 'Bob', score: 95 };
        const encrypted = encryptObject(userData, { key: 'your-secret-key' });
        console.log('加密结果:', encrypted);
        
        // 解密对象
        const decrypted = decryptObject(encrypted, { key: 'your-secret-key' });
        console.log('解密结果:', decrypted);
        // 输出: { name: 'Bob', score: 95 }
    </script>
</body>
</html>
```

### 加密/解密字符串或数字

```javascript
import { encryptValue, decryptValue } from '@lshch/okay-cipher';

// 加密字符串
const encryptedStr = encryptValue('Hello World', { key: 'your-secret-key' });
console.log('加密字符串:', encryptedStr);

const decryptedStr = decryptValue(encryptedStr, { key: 'your-secret-key' });
console.log('解密字符串:', decryptedStr);
// 输出: "Hello World"

// 加密数字
const encryptedNum = encryptValue(123456, { key: 'your-secret-key' });
console.log('加密数字:', encryptedNum);

const decryptedNum = decryptValue(encryptedNum, { key: 'your-secret-key' });
console.log('解密数字:', decryptedNum);
// 输出: 123456 (number 类型)
```

### 校验加密数据

```javascript
import { isValidObjectCipher, isValidValueCipher } from '@lshch/okay-cipher';

// 校验对象加密数据
const isValidObj = isValidObjectCipher(encrypted, { key: 'your-secret-key' });
console.log('是否为有效的对象加密数据:', isValidObj); // true

// 校验值加密数据
const isValidVal = isValidValueCipher(encryptedStr, { key: 'your-secret-key' });
console.log('是否为有效的值加密数据:', isValidVal); // true
```

## API 说明

### encryptObject(obj, options)

加密对象，只处理对象的一层，值只允许字符串或数字。

**参数:**
- `obj`: 待加密对象
- `options`: 配置项
  - `key`: 用户输入的任意长度密钥，内部会通过 SM3 转换为 16 字节 SM4 密钥

**返回值:** 格式化的加密字符串

### decryptObject(cipherStr, options)

解密对象。

**参数:**
- `cipherStr`: 已加密的分组字符串
- `options`: 配置项（需与加密时保持一致）

**返回值:** 原始对象

### encryptValue(value, options)

加密字符串或数字。

**参数:**
- `value`: 待加密的字符串或数字
- `options`: 配置项（同 encryptObject）

**返回值:** 格式化的加密字符串

### decryptValue(cipherStr, options)

解密字符串或数字。

**参数:**
- `cipherStr`: 已加密的分组字符串
- `options`: 配置项（同 encryptObject）

**返回值:** 原始字符串或数字

### isValidObjectCipher(cipherStr, options)

校验加密串是否可解密为对象。

**参数:**
- `cipherStr`: 已加密的分组字符串
- `options`: 配置项

**返回值:** Boolean

### isValidValueCipher(cipherStr, options)

校验加密串是否可解密为字符串或者数字。

**参数:**
- `cipherStr`: 已加密的分组字符串
- `options`: 配置项

**返回值:** Boolean

## 浏览器兼容性

Okay-Cipher 可以在现代浏览器和 Node.js 环境中使用。

## Node.js 版本建议

- Node.js >= 18

## 构建和开发

```bash
# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式（监听文件变化并重新构建）
npm run dev

# 运行示例&验证代码
npm run demo
```