xhshow-js

小红书请求签名生成库的 TypeScript 实现，支持 GET/POST 请求的 x-s 和 x-s-common 签名，并提供相关辅助工具。

本项目基于 xhshow 的 Python 实现移植。

📋 目录

• 特性
• 安装
• 快速开始
• API 文档
• 使用示例
• 项目结构
• 开发
• 测试
• 贡献
• 许可证

✨ 特性

• 🎯 完整功能：支持 x-s、x-s-common、x-t、x-b3-traceid、x-xray-traceid 等所有必要签名
• 📦 TypeScript 原生：完整的类型定义，提供优秀的开发体验
• 🚀 双模块支持：同时支持 ESM 和 CommonJS
• 🔐 加密支持：内置 RC4、MD5、CRC32 等加密算法
• 🎨 浏览器指纹：自动生成真实的浏览器指纹信息
• 🧪 完整测试：单元测试覆盖率 > 80%
• 📝 详细文档：中英文双语文档和示例

📦 安装

使用 npm:

npm install xhshow-js

使用 pnpm:

pnpm add xhshow-js

使用 yarn:

yarn add xhshow-js

🚀 快速开始

基础用法

import { Client } from 'xhshow-js';

// 创建客户端实例
const client = new Client();

// 准备请求参数
const a1Value = 'your_a1_cookie_value'; // 从 Cookie 中获取
const method = 'GET';
const uri = '/api/sns/web/v1/user_posted';
const payload = {
  num: 30,
  cursor: '',
  user_id: '123',
};

// 生成 x-s 签名
const xs = client.signXS(method, uri, a1Value, 'xhs-pc-web', payload);
console.log('x-s:', xs);

// 生成其他必要的头部
const xt = client.getXT();
console.log('x-t:', xt);

const b3TraceId = client.getB3TraceId();
console.log('x-b3-traceid:', b3TraceId);

const xrayTraceId = client.getXrayTraceId();
console.log('x-xray-traceid:', xrayTraceId);

// 生成 x-s-common 签名
const cookies = {
  a1: a1Value,
  web_session: 'your_web_session_value',
};
const xsCommon = client.signXSCommon(cookies);
console.log('x-s-common:', xsCommon);

POST 请求示例

const method = 'POST';
const uri = '/api/sns/web/v1/comment/post';
const payload = {
  note_id: '64ec1234567890',
  content: '不错',
  at_users: [],
};

const xs = client.signXS(method, uri, a1Value, 'xhs-pc-web', payload);

📚 API 文档

Client 类

主客户端类，提供所有签名生成功能。

构造函数

constructor();

创建一个新的客户端实例。

方法

signXS(method, uri, a1Value, xsecAppId?, payload?, timestamp?): string

生成 x-s 签名。

参数：

• method: string - HTTP 方法（'GET' 或 'POST'）
• uri: string - 请求 URI（如 /api/sns/web/v1/user_posted）
• a1Value: string - Cookie 中的 a1 值
• xsecAppId?: string - 应用标识符，默认为 'xhs-pc-web'
• payload?: RequestPayload - 请求参数（GET 为查询参数，POST 为请求体）
• timestamp?: number - 可选的时间戳（毫秒），默认使用当前时间

返回： string - 生成的 x-s 签名

signXSCommon(cookies): string

生成 x-s-common 签名。

参数：

• cookies: CookieDict - Cookie 字典，必须包含 a1 字段

返回： string - 生成的 x-s-common 签名

getXT(timestamp?): number

获取 x-t 头部值（毫秒级时间戳）。

参数：

• timestamp?: number - 可选的时间戳（秒），默认使用当前时间

返回： number - 毫秒级时间戳

getB3TraceId(): string

生成 x-b3-traceid。

返回： string - 16 字符的十六进制字符串

getXrayTraceId(timestamp?, seq?): string

生成 x-xray-traceid。

参数：

• timestamp?: number - 可选的时间戳（毫秒）
• seq?: number - 可选的序列号

返回： string - 32 字符的十六进制字符串

decodeXS(xsSignature): SignatureData

解密 x-s 签名。

参数：

• xsSignature: string - 完整的 x-s 签名（包含 XYS_ 前缀）

返回： SignatureData - 解密后的签名数据结构

decodeX3(x3Signature): Uint8Array

解密 x3 签名。

参数：

• x3Signature: string - x3 签名字符串

返回： Uint8Array - 解密后的字节数组

parseX3Payload(payload): X3Payload

解析 x3 payload。

参数：

• payload: Uint8Array - 解密后的 x3 数据

返回： X3Payload - 解析后的 payload 结构

工具函数

// Cookie 生成
generateA1(): string
registerId(): string
generateRandomString(length: number): string
getLoadTs(): string

// TraceId 生成
generateB3TraceId(): string
generateXrayTraceId(timestamp?: number, seq?: number): string

// Base64 编码/解码
encodeCustomBase64(data: Uint8Array): string
decodeCustomBase64(data: string): Uint8Array
encodeX3Base64(data: Uint8Array): string
decodeX3Base64(data: string): Uint8Array

// 随机数生成
generateRandomInt(): number
generateRandomByteInRange(minVal: number, maxVal: number): number

💻 使用示例

完整的请求示例

import { Client } from 'xhshow-js';

const client = new Client();

// 1. 准备 Cookie
const cookies = {
  a1: 'efda9b010000220000009d04000022000',
  web_session: 'your_web_session_value',
};

// 2. GET 请求
const getUri = '/api/sns/web/v1/user_posted';
const getParams = { num: 30, user_id: '123' };

const headers = {
  'x-s': client.signXS('GET', getUri, cookies.a1, 'xhs-pc-web', getParams),
  'x-t': client.getXT().toString(),
  'x-b3-traceid': client.getB3TraceId(),
  'x-xray-traceid': client.getXrayTraceId(),
  'x-s-common': client.signXSCommon(cookies),
  'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...',
};

// 使用 headers 发送请求
console.log('Request headers:', headers);

签名验证和调试

// 生成签名
const xs = client.signXS('GET', '/api/test', 'test_a1_value');

// 解密签名以验证
const decoded = client.decodeXS(xs);
console.log('签名结构:', decoded);

// 解密 x3
if (decoded.x3) {
  const x3Decoded = client.decodeX3(decoded.x3);
  const payload = client.parseX3Payload(x3Decoded);
  console.log('Payload 详情:', payload);
}

更多示例请参见 examples 目录。

📁 项目结构

xhshow-js/
├── src/
│   ├── client.ts           # 主客户端类
│   ├── config.ts           # 配置常量
│   ├── xs-common.ts        # xs-common 签名器
│   ├── types/
│   │   └── index.ts        # TypeScript 类型定义
│   ├── utils/
│   │   ├── index.ts        # 工具函数
│   │   └── cookie.ts       # Cookie 生成
│   ├── crypto/
│   │   └── index.ts        # 加密函数
│   └── fingerprint/
│       ├── data.ts         # 指纹数据配置
│       ├── helpers.ts      # 指纹辅助函数
│       └── generator.ts    # 指纹生成器
├── tests/                  # 测试文件
├── examples/               # 使用示例
├── dist/                   # 构建输出
├── package.json
├── tsconfig.json
└── README.md

🛠️ 开发

环境要求

• Node.js >= 16.0.0
• pnpm (推荐) 或 npm

安装依赖

pnpm install

构建

pnpm build

开发模式（监视文件变化）

pnpm dev

代码格式化

pnpm format

类型检查

pnpm typecheck

🧪 测试

运行所有测试：

pnpm test

运行测试并生成覆盖率报告：

pnpm test:coverage

运行示例：

# 基础示例
npx tsx examples/basic.ts

# 高级示例
npx tsx examples/advanced.ts

🤝 贡献

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🙏 致谢

• 特别感谢 Cloxl 开源的 xhshow 项目
• 感谢所有贡献者的支持

⚠️ 免责声明

本项目仅供学习和研究使用，请勿用于非法用途。使用本项目所产生的一切后果由使用者自行承担。

📮 联系方式

如有问题或建议，请提交 Issue。

Star ⭐ 本项目如果它对您有帮助！