KSO-1 签名插件

这是一个为 Yaak API 客户端设计的 KSO-1 签名算法插件，支持 KSO-1 签名和 Access Token 认证。

功能特性

• ✅ KSO-1 签名算法：完全符合 KSO-1 签名规范
• ✅ Access Token 支持：可选的 Access Token 认证
• ✅ 多种 Token 类型：支持 Bearer、Basic、Token 和自定义类型
• ✅ 动态表单：根据选择显示/隐藏相关字段
• ✅ 请求体哈希：自动计算请求体的 SHA256 哈希值
• ✅ RFC1123 日期：自动生成符合规范的日期格式

安装

1. 确保已安装 Yaak CLI 和 API 包
2. 将插件代码添加到您的项目中
3. 在 src/index.ts 中注册插件

配置参数

必需参数

• Access Key (APPID)：应用的 APPID，用于生成签名
• Secret Key (APPKEY)：应用的 APPKEY，用于生成签名

可选参数

• Access Token：访问令牌，将添加到 Authorization 头部
• Token 类型：选择 Access Token 的类型（Bearer、Basic、Token、Custom）
• 自定义 Token 类型：如果选择了 Custom，请输入自定义的 Token 类型
• 路径处理模式：选择如何提取参与签名的 RequestURI
  • 完整路径（默认）：使用完整的 URL 路径
  • 仅 API 路径（从 /v7/ 开始）：只保留从 /v7/ 开始的 API 路径
  • 自定义路径前缀：移除指定的路径前缀
• 自定义路径前缀：如果选择了自定义路径前缀，请输入要移除的前缀

生成的 HTTP 头部

插件会自动生成以下 HTTP 头部：

始终添加的头部

• Content-Type：保持原始请求的 Content-Type 或使用默认值 application/json
• X-Kso-Date：RFC1123 格式的当前 UTC 时间
• X-Kso-Authorization：KSO-1 签名值，格式为 KSO-1 <accessKey>:<signature>

条件添加的头部

• Authorization：如果提供了 Access Token，格式取决于选择的 Token 类型

签名算法

KSO-1 签名算法使用 HMAC-SHA256 计算签名，签名字符串的格式为：

官方文档参考：WPS 365 KSO-1 签名算法说明

"KSO-1" + Method + RequestURI + ContentType + KsoDate + sha256(RequestBody)

参数说明

• "KSO-1"：固定字符串，签名版本标识
• Method：HTTP 方法（GET、POST、PUT、DELETE 等）
• RequestURI：请求的 URI，包含查询参数（支持路径处理模式）
• ContentType：Content-Type 头部值
• KsoDate：RFC1123 格式的日期
• sha256(RequestBody)：请求体的 SHA256 哈希值（如果请求体为空则为空字符串）

路径处理说明

当 API 网关或代理服务器在路径前添加了前缀时，需要正确处理 RequestURI：

1. 完整路径模式（默认）：使用完整的 URL 路径

   • 例如：https://10.23.14.56/path3/path4/v7/chats?page_size=10 → /path3/path4/v7/chats?page_size=10

2. 仅 API 路径模式：只保留从 /v7/ 开始的 API 路径

   • 例如：https://10.23.14.56/path3/path4/v7/chats?page_size=10 → /v7/chats?page_size=10

3. 自定义路径前缀模式：移除指定的路径前缀

   • 例如：前缀为 /path3/path4，URL 为 https://10.23.14.56/path3/path4/v7/chats?page_size=10 → /v7/chats?page_size=10

使用示例

示例 1：仅使用 KSO-1 签名

配置：

• Access Key: AK123456
• Secret Key: sk098765
• Access Token: （留空）

生成的头部：

Content-Type: application/json
X-Kso-Date: Mon, 02 Jan 2006 15:04:05 GMT
X-Kso-Authorization: KSO-1 AK123456:c46e6c988130818ecba2484d51ac685948fbbef6814602c7874d6bfc41dc17b3

示例 2：KSO-1 签名 + Bearer Token

配置：

• Access Key: AK123456
• Secret Key: sk098765
• Access Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
• Token 类型: Bearer

生成的头部：

Content-Type: application/json
X-Kso-Date: Mon, 02 Jan 2006 15:04:05 GMT
X-Kso-Authorization: KSO-1 AK123456:c46e6c988130818ecba2484d51ac685948fbbef6814602c7874d6bfc41dc17b3
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

示例 3：KSO-1 签名 + 自定义 Token

配置：

• Access Key: AK123456
• Secret Key: sk098765
• Access Token: my-api-key-123
• Token 类型: Custom
• 自定义 Token 类型: ApiKey

生成的头部：

Content-Type: application/json
X-Kso-Date: Mon, 02 Jan 2006 15:04:05 GMT
X-Kso-Authorization: KSO-1 AK123456:c46e6c988130818ecba2484d51ac685948fbbef6814602c7874d6bfc41dc17b3
Authorization: ApiKey my-api-key-123

插件动作

插件提供了两个便捷动作：

1. 测试签名

• 显示测试消息，验证插件是否正常工作

2. 生成示例

• 显示成功消息，提示已生成示例代码

开发说明

项目结构

yaak-kso-1/
├── src/
│   ├── index.ts              # 主入口文件，注册插件
│   ├── plugins/
│   │   ├── kso-1-plugin.ts   # KSO-1 插件实现
│   │   └── kso-1-plugin.test.ts # 插件测试
├── package.json
├── tsconfig.json
└── README-kso-1.md          # 本文件

技术栈

• TypeScript
• Node.js Crypto 模块
• Yaak API 插件系统
• Vitest（测试框架）

构建和测试

# 安装依赖
npm install

# 构建插件
npm run build

# 运行测试
npx vitest run

注意事项

1. 时间同步：确保客户端和服务器的时间同步，KSO-1 签名对时间敏感
2. 请求体格式：JSON 请求体的格式会影响签名计算，确保格式一致
3. Secret Key 安全：妥善保管 Secret Key，不要泄露给第三方
4. Content-Type：如果请求没有 Content-Type 头部，插件会使用默认值 application/json
5. 路径处理：根据 API 网关配置选择合适的路径处理模式，确保 RequestURI 与服务器端计算一致

故障排除

常见问题

1. 签名验证失败：检查时间是否同步、请求体格式是否正确
2. 缺少头部：确保所有必需参数都已填写
3. Token 不生效：检查 Token 类型是否正确配置

调试建议

1. 使用插件提供的"测试签名"功能验证基本功能
2. 检查生成的 HTTP 头部是否符合预期
3. 对比服务器端的签名计算逻辑

许可证

本项目基于 MIT 许可证开源。

参考链接

• WPS 365 KSO-1 签名算法官方文档
• Yaak API 插件开发文档

支持

如有问题或建议，请提交 Issue 或联系开发者。