# @lingxiteam/security

> 灵犀安全加密包

Latest version **1.3.17** (published 2026-07-21) · ISC license · 0 weekly downloads

## Install

```sh
npm install @lingxiteam/security
pnpm add @lingxiteam/security
yarn add @lingxiteam/security
bun add @lingxiteam/security
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.3.17 |
| Published | 2026-07-21 |
| First published | 2024-04-26 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 844.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | limanpm, wanerrr, mishi-brother, hammersjs, zhang.guoyong, zzjq, diyc, goulili, pengyh, wujian666, taiyangteng, cenxiaolian, xiaohuoni, duan_duan, yaozanwen, brinkr, babelczx |

## Links

- npm: https://www.npmjs.com/package/@lingxiteam/security
- npm.io page: https://npm.io/package/@lingxiteam/security

## Dependencies (4)

- [uuid](https://npm.io/package/uuid.md) ^9.0.1
- [merge](https://npm.io/package/merge.md) ^2.1.1
- [crypto-js](https://npm.io/package/crypto-js.md) ^4.2.0
- [jsencrypt](https://npm.io/package/jsencrypt.md) ^3.3.2

## Recent versions

- 1.3.17 (latest) — 2026-07-21
- 1.3.16 — 2026-05-25
- 1.3.15 — 2025-12-22
- 1.3.14 — 2025-12-10
- 1.3.13 — 2025-12-04
- 1.3.12 — 2025-12-02
- 1.3.11 — 2025-12-02
- 1.3.10 — 2025-11-29
- 1.3.9 — 2025-11-29
- 1.3.8 — 2025-09-11
- 1.3.7 — 2025-09-11
- 1.3.6 — 2025-09-09
- 1.3.5 — 2025-09-03
- 1.3.4 — 2025-05-07
- 1.3.3 — 2025-05-07
- … 48 more at https://npm.io/package/@lingxiteam/security/versions

## README

# @lingxiteam/security ·  [![monthly downloads](https://img.shields.io/npm/dm/@lingxiteam/security)](https://www.npmjs.com/package/@lingxiteam/security) [![gitHub license](https://img.shields.io/badge/license-ISC-blue.svg)]() [![npm version](https://img.shields.io/npm/v/@lingxiteam/security.svg?style=flat)](https://www.npmjs.com/package/@lingxiteam/security)

🚀一个简单、易用、灵活的请求数据安全工具：防报文被篡改、对请求数据加解密。



## 环境支持

✅ web浏览器  [  ajax, fetch, axios, umi-request ]

✅ nodejs后端

✅ 微信小程序

✅ React Native

## 使用文档

### 安装

```shell
npm install @lingxiteam/security
```

or

```shell
yarn add @lingxiteam/security
```



### 使用

#### 简单使用

在web端：

```javascript
import { httpEncryption } from '@lingxiteam/security';

httpEncryption.start({ mode: '1.0' });
```



在小程序：

```javascript
const security = require('@lingxiteam/security').default;

security.httpEncryption.start({ mode: '1.0' });
```



#### 安全模式

| 模式值 | 模式           | 说明                                                         |
| ------ | -------------- | ------------------------------------------------------------ |
| 1.0    | 默认参数签名   | 对url地址、query参数、header参数、body参数、盐值等按照一定方式生成签名 |
| 1.1    | 时间限制性签名 | 签名内容增加时间因子，在一段时间内有效                       |
| 1.2    | 唯一限制性签名 | 生成uuid签名，仅可使用1次                                    |
| 2.0    | RSA参数加密    | 使用RSA非对称加密算法进行内容加密                            |
| 3.0    | AES参数加密    | 使用AES加密算法进行内容加密                                  |

> [!NOTE]
>
> 1. 请求内容和响应内容模式独立，即请求时使用2.0，响应可使用3.0，我们可以针对部分服务进行差异性处理，只需在响应头部返回 `Xa-type` 字段告知模式值即可。
>
> 2. 签名和加解密默认使用灵犀平台预置方式，如对接其他平台，可以通过参数配置完成[自定义](#自定义加解密)加解密处理。



#### 规则

##### mode优先级

最高：通过start方法或setConfig方法设置mode，security.httpEncryption.start({ mode: '1.0' });
其次：[后端控制](#后端控制)，当mode配置项未设置时，将读取后端的配置
缺省值 1.1

##### 全局忽略

有时候安全模式并不适用某些服务，如非灵犀平台服务、CORS请求，可以通过配置 `ignore` 规则来对符合规则的服务不触发请求和响应内容的处理。

```javascript
import { setConfig } from '@lingxiteam/security';

// 指定服务地址
setConfig({
  ignore: "api/test",
});

// 正则表达式
setConfig({
  ignore: /^https/, 
});

// 函数判断，返回true表示忽略
setConfig({
  ignore: (url, {headers, body, method}) => { /* const isIgnore = ... */ return isIgnore; }, 
});

// 多条件组合, 满足其中一个即忽略
setConfig({
  ignore: [/^https/, (url, {headers, body, method}) => { /* const isIgnore = ... */ return isIgnore; }], 
});

```



##### 单服务指定

在一些需求场景中，我们可以针对某一服务指定对应的安全模式，在请求头添加 `Xa-type` 并设置一个模式值即可，如果将该字段设置为‘false’，将不触发该请求和响应内容的处理。

注意📢：被 `ignore` 的服务无法进行指定



#### 签名加盐

在使用 cookie session的场景，往往安全要求sessionId需要设置为httpOnly，这样签名程序无法对该值进行签名，攻击者通过更改sessionId对服务发起攻击，如果接口存在疏忽没有对权限正确校验，将会出现越权操作。为最大限度进行防范，建议增加一个以用户信息(userId、userCode)作为盐。

```javascript
// web端
import { setConfig, lxEncrypt } from '@lingxiteam/security';
setConfig({ sign: { saltKey: 'userId' } }); // 自动从cookie上获取值

// 非web端或cookie不可使用
setConfig({ sign: { saltKey: 'userId', saltValue: '...' } });
```



#### 资源地址签名

当通过 `img、script、link` 等标签方式加载资源时，无法通过请求头进行添加签名，我们可以使用 `createHttpSignWithUrl` 方法为资源地址后添加签名参数

```javascript
import { createHttpSignWithUrl } from '@lingxiteam/security';

const imgSrc = createHttpSignWithUrl('/app/file/id/123');

```



#### 自定义加解密

通过 `setConfig` 方法进行自定义配置

```javascript
import { setConfig, lxEncrypt } from '@lingxiteam/security';

// 密钥配置均支持经过lxEncrypt方法二次加密内容
setConfig({
  rsa: {
    // RSA公钥
    publicKey: '...',
    // RSA私钥
    privKey: '...',
    // 自定义RSA加密，返回加密后内容
    encrypt: (conetnt, publicKey) => '...',
    // 自定义RSA解密，返回解密后内容
    decrypt: (conetnt, privKey) => '...',
  },
  
  aes: {
    // AES密钥
    key: '...',
    // 自定义AES加密，返回加密后内容
    encrypt: (conetnt, key) => '...',
    // 自定义AES解密，返回解密后内容
    decrypt: (conetnt, key) => '...',
  }

  
  // 支持密钥二次加密
  keyEncrypt: true,
});

```



#### 后端控制

在web端可以引入服务器上`app/env/info.js` ，并通过平台界面配置来动态控制安全模式相关配置。

在小程序上可以根据服务返回的参数进行设置：

```javascript
const security = require('@lingxiteam/security').default;

// 与平台对接，单点后拿到 refreshAccessToken、secretKey、secretValue、accessToken、lxServerTime、lxSecurityMode
// 启动安全签名
security.httpEncryption.start({
    mode: lxSecurityMode,
    sign: {
        saltKey: secretKey,
        saltValue: secretValue,
    },
    serverTime: lxServerTime,
});
```





#### 手动模式

当执行 `httpEncryption.start()` 后，程序进行将自动处理所有异步请求，执行 `httpEncryption.stop()` 将释放控制权。如果自动模式无法满足或出现与其他程序使用不兼容，可以通过使用原始的方法自行进行处理。

```javascript
import { createHttpSignStr, RSAEncrypt, RSADecrypt, AESEncrypt, AESDecrypt, DESEncrypt, DESDecrypt } from '@lingxiteam/security';

// 生成签名
const xSign = createHttpSignStr(url, { headers, body, method, saltValue }, signMode);

// 加密
const RSAEncryptContent = RSAEncrypt(content, key);
const AESEncryptContent = AESEncrypt(content, key);
const DESEncryptContent = DESEncrypt(content, key);

// 解密
const RSADecryptContent = RSADecrypt(content, key);
const AESDecryptContent = AESDecrypt(content, key);
const DESDecryptContent = DESDecrypt(content, key);
```



#### 其他

##### 空值body

当body为空时，可能出现前后端取值不一致问题。nodejs后端一般存在空字符串、空对象、undefined 等值，这取决于框架处理和使用的中间件；java后端一般为null。为避免前后端取值差异导致签名校验失败，可以通过配置项将前端空值进行转换与后端保持一致。缺省值为空字符串。

```javascript
import { setConfig } from '@lingxiteam/security';

setConfig({ emptyBodyValue: '{}' });
```

##### webpack5下使用

使用webpack5工程出现 Module not found: Error: Can't resolve 'crypto', 此时需要调整webpack配置项

```json
{
  "resolve": {
    "fallback": {
      "crypto": false
    }
  }
}
```



### 调试

设置debug模式，控制台将输出相关日志信息

```javascript
// 配置设置
import { setConfig } from '@lingxiteam/security';

setConfig({ debug: true });

// or 
localStorage.setItem('lxDebug', 'true');
```

---
_Source: https://npm.io/package/@lingxiteam/security · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._