@ikenxuan/xhshow-ts

v1.0.6

Published

a month ago

XHS API signature generator

0High
0Medium
0Low

ikenxuan

xhs signature api

xhshow-ts

小红书请求签名生成库的 TypeScript 实现，支持 GET/POST 请求的 x-s 和 x-s-common 签名。

本项目基于 Cloxl/xhshow 的 Python 实现移植而来，感谢原作者的无私奉献！

⚠️ 声明：本 Fork 代码由 AI 辅助生成，仅供学习研究使用，不保证与上游仓库行为完全一致。

致谢

特别感谢 Cloxl 开源的 xhshow 项目，本项目的核心算法逻辑均来源于此。

系统要求

Node.js 16+
TypeScript 5.0+（可选，用于开发）

安装

npm install @ikenxuan/xhshow-ts

或使用其他包管理器：

# yarn
yarn add @ikenxuan/xhshow-ts

# pnpm
pnpm add @ikenxuan/xhshow-ts

快速开始

ESM（推荐）

import { Xhshow } from '@ikenxuan/xhshow-ts'

const client = new Xhshow()

// GET 请求签名
const getSignature = client.signXsGet(
  '/api/sns/web/v1/user_posted',
  'your_a1_cookie_value',
  'xhs-pc-web',
  { num: '30', cursor: '', user_id: '123' }
)

// POST 请求签名
const postSignature = client.signXsPost(
  '/api/sns/web/v1/login',
  'your_a1_cookie_value',
  'xhs-pc-web',
  { username: 'test', password: '123456' }
)

// x-s-common 签名
const xsCommon = client.signXsc({
  a1: 'your_a1_cookie_value',
  web_session: 'your_web_session'
})

// 一次性生成所有请求头
const headers = client.signHeadersGet(
  '/api/sns/web/v1/user_posted',
  { a1: 'your_a1_cookie_value', web_session: '...' },
  'xhs-pc-web',
  { num: '30' }
)
// headers 包含: x-s, x-s-common, x-t, x-b3-traceid, x-xray-traceid

使用会话管理（推荐）

会话管理器可以模拟真实用户在同一页面中的连续操作，生成更真实的签名，提高长期稳定性：

import { Xhshow, SessionManager } from '@ikenxuan/xhshow-ts'

const client = new Xhshow()
const session = new SessionManager()

// 使用会话管理器进行多次请求
const headers1 = client.signHeadersGet(
  '/api/sns/web/v1/user_posted',
  { a1: 'your_a1_cookie_value', web_session: '...' },
  'xhs-pc-web',
  { num: '30' },
  undefined,
  session  // 传入会话管理器
)

// 第二次请求，会话状态会自动更新
const headers2 = client.signHeadersGet(
  '/api/sns/web/v1/user_posted',
  { a1: 'your_a1_cookie_value', web_session: '...' },
  'xhs-pc-web',
  { num: '30', cursor: 'next_page' },
  undefined,
  session  // 使用同一个会话管理器
)

// 会话管理器的工作原理：
// - 无 Session：每次请求生成随机参数，可能被识别为机器人
// - 有 Session：维护固定的页面加载时间戳和单调递增的计数器，模拟真实用户行为

CommonJS

const { Xhshow } = require('@ikenxuan/xhshow-ts')

const client = new Xhshow()

const getSignature = client.signXsGet(
  '/api/sns/web/v1/user_posted',
  'your_a1_cookie_value',
  'xhs-pc-web',
  { num: '30', cursor: '', user_id: '123' }
)

API 参考

签名方法

| 方法 | 说明 | |------|------| | signXs(method, uri, a1Value, xsecAppid?, payload?, timestamp?, session?) | 通用签名 | | signXsGet(uri, a1Value, xsecAppid?, params?, timestamp?, session?) | GET 请求签名 | | signXsPost(uri, a1Value, xsecAppid?, payload?, timestamp?, session?) | POST 请求签名 | | signXsc(cookieDict) | 生成 x-s-common 签名 |

请求头生成

| 方法 | 说明 | |------|------| | signHeaders(method, uri, cookies, xsecAppid?, params?, payload?, timestamp?, session?) | 生成完整请求头 | | signHeadersGet(uri, cookies, xsecAppid?, params?, timestamp?, session?) | GET 请求头 | | signHeadersPost(uri, cookies, xsecAppid?, payload?, timestamp?, session?) | POST 请求头 |

会话管理

| 类/方法 | 说明 | |------|------| | SessionManager | 会话管理器类 | | session.getCurrentState(uri) | 获取当前签名状态 | | session.updateState() | 更新会话状态 |

工具方法

| 方法 | 说明 | |------|------| | decodeXs(xsSignature) | 解密 XYS 签名 | | decodeX3(x3Signature) | 解密 x3 签名 | | buildUrl(baseUrl, params?) | 构建带参数的 URL | | buildJsonBody(payload) | 构建 JSON body | | getB3TraceId() | 生成 x-b3-traceid | | getXrayTraceId(timestamp?, seq?) | 生成 x-xray-traceid | | getXT(timestamp?) | 生成 x-t 时间戳 |

类型定义

type Method = 'GET' | 'POST'
type Payload = Record<string, any> | null

interface SignState {
  pageLoadTimestamp: number
  sequenceValue: number
  windowPropsLength: number
  uriLength: number
}

class SessionManager {
  constructor(config?: CryptoConfig)
  updateState(): void
  getCurrentState(uri: string): SignState
}

interface Xhshow {
  signXs(method: Method, uri: string, a1Value: string, xsecAppid?: string, payload?: Payload, timestamp?: number, session?: SessionManager): string
  signXsGet(uri: string, a1Value: string, xsecAppid?: string, params?: Payload, timestamp?: number, session?: SessionManager): string
  signXsPost(uri: string, a1Value: string, xsecAppid?: string, payload?: Payload, timestamp?: number, session?: SessionManager): string
  signXsc(cookieDict: Record<string, any> | string): string
  signHeaders(method: Method, uri: string, cookies: Record<string, any> | string, xsecAppid?: string, params?: Payload, payload?: Payload, timestamp?: number, session?: SessionManager): Record<string, string>
  signHeadersGet(uri: string, cookies: Record<string, any> | string, xsecAppid?: string, params?: Payload, timestamp?: number, session?: SessionManager): Record<string, string>
  signHeadersPost(uri: string, cookies: Record<string, any> | string, xsecAppid?: string, payload?: Payload, timestamp?: number, session?: SessionManager): Record<string, string>
  decodeXs(xsSignature: string): Record<string, any>
  decodeX3(x3Signature: string): Uint8Array
  buildUrl(baseUrl: string, params?: Record<string, any> | null): string
  buildJsonBody(payload: Record<string, any>): string
  getB3TraceId(): string
  getXrayTraceId(timestamp?: number, seq?: number): string
  getXT(timestamp?: number): number
}

开发

# 克隆项目
git clone https://github.com/ikenxuan/xhshow-ts
cd xhshow-ts

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

项目结构

src/
├── client.ts          # 主客户端类
├── session.ts         # 会话管理器
├── core/              # 核心加密处理
├── config/            # 配置
├── data/              # 指纹数据
├── generators/        # 指纹生成器
├── utils/             # 工具函数
└── validators.ts      # 参数验证

License

MIT