@ikenxuan/amagi 7.0.0-beta.7 → 7.0.0-beta.8

package/dist/exports/signing.d.ts

@@ -1,3 +1,128 @@
+import "../endpoint-QPR2Pp-S.js";
+import { a as WEBSIGN_CONST, c as isSecsdkProtected, d as av2bv, f as bv2av, i as SecsdkSignResult, l as signSecsdkWebQuery, n as SECSDK_SIG_KEY, o as canonicalQuery, r as SecsdkSignOptions, s as extractUifidFromCookie, u as signSecsdkWebUrl } from "../secsdkWebSign-DoqHj52s.js";
+//#region src/platforms/kuaishou/sign/hudr.d.ts
+/**
+ * 快手 `window.SECS` 的最小状态描述。
+ */
+type KuaishouSecsState = {
+  c?: number;
+  s?: string;
+};
+/**
+ * 生成 `HUDR_` 段所需的上下文参数。
+ */
+type KuaishouHudrContext = {
+  count: number;
+  scriptCount?: number;
+  secs?: KuaishouSecsState;
+};
+/**
+ * 快手 `HUDR_` 段的中间结果。
+ */
+type KuaishouHudrResult = {
+  body: string;
+  full: string;
+  infoCache: number[];
+  maskedPayload: Uint8Array;
+  nextCount: number;
+};
+//#endregion
+//#region src/platforms/kuaishou/sign/he.d.ts
+/**
+ * 生成快手 `$HE_` 段所需的上下文参数。
+ */
+type KuaishouHeContext = {
+  count: number;
+  hudrBody: string;
+  randomValue: number;
+  signInput: string;
+  startupRandom: number;
+  timestamp: number;
+};
+/**
+ * 快手完整纯算法签名所需的上下文参数。
+ */
+type KuaishouPureSignContext = KuaishouHudrContext & {
+  randomValue: number;
+  signInput: string;
+  startupRandom: number;
+  timestamp: number;
+};
+/**
+ * 快手 `$HE_` 段的中间结果。
+ */
+type KuaishouHeResult = {
+  finalHex: string;
+  hashFieldHex: string;
+  preHex: string;
+};
+/**
+ * 快手纯算法签名的完整结果。
+ */
+type KuaishouPureSignResult = KuaishouHudrResult & {
+  he: KuaishouHeResult;
+  signResult: string;
+};
+/**
+ * 计算 `$HE_` 中的 hash field。
+ *
+ * 它由 `signInput + HUDRBody` 经 `b2sa -> cts -> 截断 -> 异或掩码`
+ * 这条链路导出，是 `$HE_` 中与接口输入最直接相关的一段。
+ *
+ * @param signInput - 快手 `__NS_hxfalcon` 的 sign input
+ * @param hudrBody - `HUDR_` 去前缀后的主体
+ * @returns `$HE_` 载荷中的 4 字节 hash field hex
+ */
+export declare const deriveKuaishouHeHashFieldHex: (signInput: string, hudrBody: string) => string;
+/**
+ * 推导快手签名中的 `$HE_` 段。
+ *
+ * @param context - 生成 `$HE_` 所需的上下文参数
+ * @returns `$HE_` 的最终 hex、中间 hash field 和 preHex
+ */
+export declare const deriveKuaishouHeHex: (context: KuaishouHeContext) => KuaishouHeResult;
+/**
+ * 一次性推导快手完整纯算法签名。
+ *
+ * 该方法会先生成 `HUDR_`，再拼出 `$HE_`，最终返回完整
+ * `HUDR_...$HE_...` 形式的 `__NS_hxfalcon`。
+ *
+ * @param context - 快手纯算法签名上下文
+ * @returns 完整签名结果及关键中间态
+ */
+export declare const deriveKuaishouPureSignature: (context: KuaishouPureSignContext) => KuaishouPureSignResult;
+/** 结构检查能发现的问题。真实签名永远一个都不该有 */
+type KuaishouHeProblem = 'not hex' | 'length not 90' | 'envelope checksum' | 'tail lrc' | 'header magic' | 'version' | 'startup marker' | 'fixed body' | 'tail';
+/** {@link decodeKuaishouHe} 的拆解结果 */
+interface DecodedKuaishouHe {
+  /** 页面加载时的一次性随机数（LE 6 字节，原样读回） */
+  startupRandom: number;
+  /** 本条签名自己的 48 位随机数（LE 6 字节，原样读回） */
+  random: number;
+  /** 签名计数器（异或掩码已解掉） */
+  count: number;
+  /** 毫秒时间戳（异或掩码已解掉）—— 与 a_bogus 的毫秒时钟同源，都是 Date.now() 一路 */
+  timestampMs: number;
+  /** 4 字节 hash field（十六进制）。重算它需要 signInput 与 HUDR body，见 {@link deriveKuaishouHeHashFieldHex} */
+  hashFieldHex: string;
+  /** 发现的全部问题；空数组 = 结构良好 */
+  problems: KuaishouHeProblem[];
+}
+/**
+ * 拆开一段 `$HE_`。
+ *
+ * 最终输出的最后一个字节是**异或键**：它本身是前 44 字节的 LRC 校验，同时把那
+ * 44 字节逐个异或成密文 —— 所以解码顺序固定为「拆键 → 还原 → 逐段校验 → 读字段」。
+ * 能同时通过两层校验（信封 LRC + 尾段 LRC）与四个布局常量的值，必然是这套装配
+ * 顺序产出的；`count` 与时间戳随后原样读回，不需要任何候选输入。
+ *
+ * 它**不**校验 hash field —— 那四字节绑的是 signInput + HUDR body，候选值给齐了
+ * 可用 {@link deriveKuaishouHeHashFieldHex} 自行比对。
+ * @param hex - `$HE_` 后面的那段 hex（90 个字符）
+ * @returns 拆解结果；布局不符时 `problems` 非空，字段值不可信
+ */
+export declare const decodeKuaishouHe: (hex: string) => DecodedKuaishouHe;
+//#endregion
 //#region src/platforms/douyin/sign/a_bogus.d.ts
 /**
  * a_bogus —— 抖音 Web 加在每个数据接口上的签名。
@@ -694,5 +819,165 @@ export declare const DOUYIN_TTWID_PAYLOAD: {
 };
 /** 抖音访客 ttwid 注册：`POST {url}`，body 用 `data` */
 export declare const DOUYIN_TTWID: TtwidSpec;
+/** 结构检查能发现的问题。真值永远一个都不该有 */
+type VerifyFpProblem = 'prefix' | 'tail length' | 'separators' | 'version' | 'variant' | 'alphabet';
+/** {@link decodeVerifyFp} 的拆解结果 */
+interface DecodedVerifyFp {
+  /** 毫秒时间戳（36 进制段原样还原，无任何推断） */
+  timestampMs: number;
+  /** 发现的全部问题；空数组 = 结构良好 */
+  problems: VerifyFpProblem[];
+}
+/**
+ * 拆开一个 `verify_fp` / `s_v_web_id`。
+ *
+ * 这类值的唯一真实载荷就是**生成时刻**（`verify_<36 进制毫秒>_<36 位 UUID v4 骨架>`），
+ * 其余 31 个字符是纯随机。骨架的四个位置常量（分隔符、版本位、变体位）加上字母表
+ * 约束构成指纹；时钟能原样读回，所以「这条 verify_fp 是什么时候生成的」是可判定的。
+ *
+ * 它**不能**辨别真假：假值的形状目标就是与真值一致（见 {@link genVerifyFp}）。
+ * @param value - 待检查的值
+ * @returns 拆解结果；骨架不符时 `problems` 非空
+ */
+export declare const decodeVerifyFp: (value: string) => DecodedVerifyFp;
+//#endregion
+//#region src/platforms/douyin/sign/x_bogus.d.ts
+/** 站点混在时间戳旁边的固定常量 */
+export declare const CANVAS_CONSTANT = 536919696;
+/** X-Bogus 签名算法的返回结果 */
+interface XBogusResult {
+  /** 已拼上 `X-Bogus=` 的完整 URL */
+  fullUrl: string;
+  /** 签名值本身，28 个字符 */
+  xbogus: string;
+  /** 实际参与签名的 User-Agent */
+  userAgent: string;
+}
+/** {@link XBogus.getXBogus} 的注入点 */
+interface XBogusOptions {
+  /**
+   * 秒级 Unix 时间戳，默认 `Math.floor(Date.now() / 1000)`。
+   *
+   * 签名里封着它（4 个字节），所以同一秒内两次调用结果相同，钉死它才能复现一份签名
+   * —— 这既是对拍浏览器输出的前提，也是快照测试能成立的原因。
+   */
+  timestamp?: number;
+}
+declare class XBogus {
+  /** V4 兼容字段：V4 会把结果同步写进 `params` / `xb`，本实现不写 */
+  params?: string;
+  xb?: string;
+  /**
+   * 生成 X-Bogus 签名。
+   *
+   * @param url - 完整的 URL 地址（签的是它的 pathname + search）
+   * @param ua - 可选的 User-Agent，不提供则使用默认值
+   * @param options - `timestamp` 注入点（秒级），省略时取当前时间
+   * @returns 完整 URL（已带 `X-Bogus=`）、签名值与实际使用的 User-Agent
+   */
+  getXBogus(url: string, ua?: string, options?: XBogusOptions): XBogusResult;
+}
+/**
+ * 对一条 path+search 签出 X-Bogus。
+ *
+ * {@link XBogus.getXBogus} 的函数式形态 —— 验证工具要用它对候选输入重签；
+ * 输入是已经拆好的 `pathname + search`，不重复解析 URL。
+ * @param urlPath - 参与 签名的 `pathname + search`
+ * @param userAgent - 参与签名的 User-Agent
+ * @param timestamp - 秒级时间戳
+ * @returns 28 个字符的签名值
+ */
+export declare const signXBogus: (urlPath: string, userAgent: string, timestamp: number) => string;
+/** 结构检查能发现的问题。真实签名永远一个都不该有 */
+type XBogusProblem = 'alphabet' | 'length not 28' | 'envelope lead' | 'lead slots' | 'empty digest' | 'canvas constant' | 'checksum';
+/**
+ * 只凭签名本身能做的全部检查 —— 不需要任何候选输入。
+ *
+ * X-Bogus 里封着三个**常量**（载荷前四格、empty 摘要链字节、canvas 常量），
+ * 它们与校验位一起构成指纹：一份能通过全部检查的值，必然出自这套算法的装配顺序。
+ * @param value - 待检查的值（28 个字符）
+ * @returns 第一个发现的问题；`null` 表示全部通过
+ */
+export declare const xBogusStructureError: (value: string) => XBogusProblem | null;
+/** {@link decodeXBogus} 的候选输入。给了哪个就校验哪条链 */
+interface XBogusCandidates {
+  /** 签名所覆盖的 `pathname + search`（不含 `X-Bogus` 自身） */
+  query?: string;
+  userAgent?: string;
+}
+/**
+ * 拆开一份 X-Bogus，并就调用方给出的候选值做校验。
+ *
+ * 能原样读回的只有一个值：秒级时间戳。三条摘要链各留两个字节（16 位），输入无法
+ * 从中倒推，做的是校验 —— 给候选值，回答是不是它封的那一个。证据量比 a_bogus
+ * 的 24 位小，但足以区分「对着的 URL」与「差一个参数的 URL」。
+ * @param value - X-Bogus 的值（28 个字符）
+ * @param candidates - 候选的 path+search 与 User-Agent，给哪个校验哪个
+ * @returns 拆解结果；格式不合法时 `recovered` 为 `false` 并给出 `reason`
+ */
+export declare const decodeXBogus: (value: string, candidates?: XBogusCandidates) => Decoded;
+//#endregion
+//#region src/platforms/bilibili/sign/wbi.d.ts
+/** 从 URL 末尾取文件名部分（去扩展名），得到 img_key / sub_key */
+declare const extractKey: (url: string) => string;
+/** 签名参数值类型 */
+type SignParamValue = string | number | boolean;
+/**
+ * 一次 wbi 签名的全部产物。
+ */
+interface WbiSignature {
+  /** 参与签名的秒级时间戳，同时是要发送的 `wts` */
+  wts: number;
+  /** 32 位小写十六进制的 `w_rid` */
+  w_rid: string;
+  /** 实际参与哈希的规范化 query（已含 `wts`，按 key 排序、值滤掉 `!'()*`） */
+  canonicalQuery: string;
+  /** 由 img_key + sub_key 打乱出的 32 位混合密钥 */
+  mixinKey: string;
+}
+/**
+ * 按给定时间戳计算 wbi 签名 —— **验证工具与 {@link encWbi} 共用的唯一实现**。
+ *
+ * 不修改传入的 `params`；时钟由调用方注入，所以对一份已签名的 URL 重算
+ * `w_rid` 时可以钉死它自己的 `wts`，逐字符复现。
+ * @param params - 请求参数（不含 wts / w_rid）
+ * @param img_key - 图片密钥
+ * @param sub_key - 子密钥
+ * @param wts - 秒级时间戳
+ * @returns 签名产物
+ */
+export declare const computeWbiSignature: (params: Record<string, SignParamValue>, img_key: string, sub_key: string, wts: number) => WbiSignature;
+//#endregion
+//#region src/platforms/xiaohongshu/sign/shape.d.ts
+/**
+ * 小红书反爬头部的**形状检查** —— 验证工具在小红书这边能做的全部事情。
+ *
+ * 真正的签名算法在 `@ikenxuan/xhshow-ts` 里，那条依赖链用了 `node:crypto` 与
+ * `node:zlib`，进不了浏览器；所以与 a_bogus / X-Bogus 那种「拆开验」不同，
+ * 小红书在这里只能验形状：前缀、长度、字符集、时钟的合理范围。这不是偷工减料
+ * ——XYS_/XYW_ 前缀区分两套协议（数据接口 2026-03 起拒收 XYS_），x-t 的时钟
+ * 范围能暴露「拿秒当毫秒」这类错，形状本身就有鉴别力。
+ *
+ * 本文件**不得** import `./index`（它会拉进 `@ikenxuan/xhshow-ts`，整条
+ * `@ikenxuan/amagi/signing` 的浏览器可用性就毁了）。它只认传入的字符串。
+ *
+ * @module platforms/xiaohongshu/sign/shape
+ */
+/** 一个头部被检查后的结果 */
+interface XhsHeaderInspection {
+  /** 头名（原样返回，方便调用方渲染） */
+  name: string;
+  /** x-s 独有：识别出的协议格式 */
+  format?: 'XYS' | 'XYW';
+  /** 发现的全部问题；空数组 = 形状良好 */
+  problems: string[];
+}
+/**
+ * 检查一个签名头部的形状。
+ * @param name - 头名（`x-s` / `x-s-common` / `x-t` / `x-xray-traceid` / `x-b3-traceid`）
+ * @param value - 头部的值
+ * @returns 检查结果；不认识的头名按「非空」处理
+ */
+export declare const inspectXhsHeader: (name: string, value: string) => XhsHeaderInspection;
 //#endregion
-export type { ABogusCandidates, ABogusOptions, ABogusSignOptions, Check, Decoded, DecodedABogus, DigestChain, Field, MsTokenSpec, SaltDiagnosis, SignedQueryRecovery, TtwidSpec, VerifyFpOptions };
+export { type ABogusCandidates, type ABogusOptions, type ABogusSignOptions, type Check, type Decoded, type DecodedABogus, type DecodedKuaishouHe, type DecodedVerifyFp, type DigestChain, type Field, type KuaishouHeProblem, type KuaishouPureSignContext, type MsTokenSpec, SECSDK_SIG_KEY, type SaltDiagnosis, type SecsdkSignOptions, type SecsdkSignResult, type SignedQueryRecovery, type TtwidSpec, type VerifyFpOptions, type VerifyFpProblem, WEBSIGN_CONST, type WbiSignature, XBogus, type XBogusCandidates, type XBogusOptions, type XBogusProblem, type XBogusResult, type XhsHeaderInspection, av2bv, bv2av, extractUifidFromCookie, extractKey as extractWbiKey, isSecsdkProtected, canonicalQuery as secsdkCanonicalQuery, signSecsdkWebQuery, signSecsdkWebUrl };