sjht-security

一个基于 axios 的自动加解密拦截器工具，提供透明的请求加密和响应解密功能，支持 SM4 加密算法。 注意：后端必须接入对应版本的sdk，才能正常使用该工具。

功能特性

• 🔒 自动请求加密：支持 JSON 数据自动加密
• 📦 自动响应解密：根据响应头自动解密加密数据
• 🔑 密钥管理：自动管理和更新加密密钥
• 📋 请求排队：避免并发请求导致的密钥同步问题
• 🔄 智能重试：处理密钥过期等场景的自动重试机制
• 🎯 业务无感知：对业务代码透明，无需修改现有请求逻辑

安装

# npm
npm install sjht-security

# yarn
yarn add sjht-security

快速开始

基本使用

import axios from 'axios';
import { createSecureClient } from 'sjht-security';

// 创建新的加密客户端，用它来发起请求
const { secureClient } = createSecureClient();

// 添加请求拦截器
secureClient.interceptors.request.use(config => {
  // 根据实际接口需要，标识该接口需要加密,如果不需要加密，不要传这个字段
  config.headers.isEncrypt = true;
  return config;
});

// 添加响应拦截器
secureClient.interceptors.response.use(res => {
  // 解密之后的响应数据
  // 其他拦截逻辑...
  return res;
});
// 导出使用
export default secureClient;

// 使用加密客户端发送请求
secureClient.post('/api/data', {
  username: 'test',
  password: '123456'
}).then(response => {
  console.log('解密后的数据:', response.data);
});

结合项目原有拦截器使用

import axios from 'axios';
import { createSecureClient } from 'sjht-security';

// 原项目的 axios 实例
const service = axios.create({
  timeout: 50000
});

// 复用原有的axios实例，给它挂载加解密拦截器
// 注意！！！ 需要放在业务原本的请求拦截器之前
createSecureClient({},service);

// 项目原本的请求拦截器
service.interceptors.request.use(config => {
  // 添加认证信息等
  config.headers.Authorization = 'Bearer token';
  // 根据实际接口需要，标识该接口需要加密,如果不需要加密，不要传这个字段
  config.headers.isEncrypt = true;
  return config;
});

// 项目原本的响应拦截器
service.interceptors.response.use(res => {
  // 解密之后的响应数据
  // 其他拦截逻辑...
  return res;
});

// 导出使用
export default service;

// 原来怎么用就怎么用
service.post('/api/data', {
  username: 'test',
  password: '123456'
}).then(response => {
  console.log('解密后的数据:', response.data);
});

// 或者单独使用加解密拦截器

// 原项目的 axios 实例
const service = axios.create();
const { decryptResponseInterceptor, encryptRequestInterceptor } = createSecureClient({ autoInterceptor: false }, service);
// 先添加请求加密拦截器
service.interceptors.request.use(encryptRequestInterceptor);
// 其他请求拦截器
service.interceptors.request.use(config => {
  // 根据实际接口需要，标识该接口需要加密,如果不需要加密，不要传这个字段
  config.headers.isEncrypt = true;
  return config;
});
// 其他响应拦截器方式
// ...
// 最后添加响应解密拦截器
service.interceptors.response.use(decryptResponseInterceptor);

直接使用axios静态方法

import axios from 'axios';
import { createSecureClient } from 'sjht-security';

// 创建加密客户端，传入axios.create创建的实例
// axios.create 可以自定义配置，也可以空配置，目的是将拦截器挂在axios上
createSecureClient({}, axios);

// 根据实际接口需要，标识该接口需要加密,如果不需要加密，不要传这个字段
axios.defaults.headers.isEncrypt = true;

// 使用加密客户端发送请求
axios.post('/api/data', {
  username: 'test',
  password: '123456'
}).then(response => {
  console.log('解密后的数据:', response.data);
});

一个原则：拦截器挂载在谁身上，就用谁去发起请求

API 文档

createSecureClient(options, axiosInstance?)

创建一个具备加解密功能的 axios 实例。

参数:

• options (SecureOptions): 配置选项
  • autoInterceptor? (boolean): 是否自动挂载加解密拦截器（可选，默认 true）
  • cryptMode? (ECryptMode): 加密模式 1:sm4对称加密 2:sm2 + sm4 加密（可选，默认 1）
  • retryBefore? ((config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig): 重试前处理函数，给调用方一个修改请求配置的钩子，但是必须返回新的配置（可选）
• axiosInstance? (AxiosInstance): 自定义 axios 实例（可选，默认创建新实例）

返回值:

• secureClient (AxiosInstance): 具备加解密功能的 axios 实例
• encryptRequestInterceptor (Function): 请求加密拦截器函数（当 autoInterceptor 为 false 时可用）
• decryptResponseInterceptor (Function): 响应解密拦截器函数（当 autoInterceptor 为 false 时可用）

getSecurityRequestConfig(config)

请求加密处理工具函数，用于手动对请求配置进行加密处理。

参数:

• config (any): 请求配置对象，包含 url、data、method、headers 等字段

返回值:

• Promise<any>: 加密处理后的请求配置对象

使用场景: 当需要手动控制加密过程，而不使用自动拦截器时使用。

getSecurityResponseData(res, req, callback)

响应解密处理工具函数，用于手动对响应进行解密处理，支持自动重试机制。

参数:

• res (any): 响应对象
• req (any): 请求配置对象
• callback (Object): 回调函数对象
  • handle408? (Function): 处理 408 状态码的回调函数（可选）
  • handle409? (Function): 处理 409 状态码的回调函数（可选）
  • client? (Function): 用于发起重试请求的客户端函数（可选）
  • retryBefore? (Function): 重试请求前的处理函数，可用于修改重试配置（可选）

返回值:

• Promise<any>: 解密处理后的响应对象

使用场景: 当需要手动控制解密过程，而不使用自动拦截器时使用。

工作原理

请求流程

1. 密钥检查：检查是否存在有效的 SM4 密钥，如不存在则对需要加密的请求启用排队
2. 请求拦截：拦截器自动检测请求数据类型，对data进行 SM4 加密
3. 发送请求：发送加密后的请求到服务器

响应流程

1. 响应拦截：检查响应头是否包含 safe-mode 标识
2. 自动解密：如果是加密响应，使用 SM4 进行解密
3. 状态处理：根据响应状态码进行不同处理
   • 408: 需要加密，自动获取密钥并当前重试请求，同时释放排队请求
   • 409: 密钥获取失败，自动重试或返回明文
   • 410: 密钥过期，自动更新密钥

状态码说明

| 状态码 | 含义 | 处理方式 | |--------|------|----------| | 408 | 需要加密 | 自动获取密钥并重试请求 | | 409 | 密钥获取失败 | 移除加密配置，使用明文请求 | | 410 | 密钥即将过期 | 自动更新密钥，继续处理响应 |

注意事项

1. 依赖要求：需要 axios 版本 >= 0.27.0
2. 加密算法：使用 SM4 加密算法，内部依赖 sm-crypto 库
3. 密钥管理：密钥默认存储在 sessionStorage 中，确保环境支持
4. 请求顺序：加密请求会自动排队，确保密钥同步
5. 业务拦截器：需要加密的请求必须在请求headers中添加 isEncrypt: true 字段，否则会被当作明文请求处理
6. 执行顺序：因为axios请求拦截器是先注册后执行，响应拦截器是先注册先执行，所以createSecureClient必须放在原有拦截器之前

开发

构建项目

npm run build

本地测试

本地构建

npm run build           # 打包项目
npm link                # 链接项目到全局
cd your-app/            # 进入自己项目目录
npm link sjht-security   # 链接 sjht-security 到自己项目

项目结构

src/
├── cache.ts          # 缓存管理
├── common.ts         # 通用工具和常量
├── config.ts         # 配置管理
├── crypt.ts          # 加密解密核心逻辑
├── index.ts          # 入口文件
├── interceptor.ts    # axios 拦截器实现
├── types.ts          # 类型定义
└── utils.ts          # 工具函数

License

Copyright © 2025 <世纪恒通股份有限公司>
All rights reserved.

本项目为闭源软件，本仓库仅放置文档与发布包。