@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/html.d.mts

@@ -0,0 +1,103 @@
+import { HTMLElement } from "node-html-parser";
+/**
+ * HTML 转义与反转义工具。
+ *
+ * 基于 `fast-escape-html` 实现，用于在把不可信文本嵌入 HTML 前进行转义，
+ * 或将已转义的 HTML 实体还原为原始字符，避免标签错乱与 XSS 注入。
+ *
+ * 转义字符对照：
+ * | 原字符 | 转义结果 |
+ * | ------ | -------- |
+ * | `&`    | `&`  |
+ * | `<`    | `&lt;`   |
+ * | `>`    | `&gt;`   |
+ * | `"`    | `&quot;` |
+ * | `'`    | `&#39;`  |
+ *
+ * @example
+ * const html = new XHtml();
+ * html.escape('<a href="x">\'</a>') // '&lt;a href=&quot;x&quot;&gt;&#39;&lt;/a&gt;'
+ * html.unescape('&lt;a&amp;b&gt;') // '<a&b>'
+ *
+ * @remarks
+ * - `escape` 是无状态转义：已含实体的文本会再次被转义（如 `&lt;` →
+ *   `&amp;lt;`），因此不要对同一段文本重复调用；
+ * - `unescape` 只还原本工具转义出的实体（`&amp;`、`&lt;`、`&gt;`、
+ *   `&quot;`、`&#39;`、`&apos;`），不处理 `&nbsp;`、`&copy;` 等其它命名
+ *   实体，也不处理 `&#65;`、`&#x41;` 这类十进制/十六进制数字实体；
+ * - 本工具面向 HTML 文本节点/属性值的转义场景，不负责 URL 编码，也不保证
+ *   脚本、样式等非 HTML 上下文的安全。
+ */
+export declare class XHtml {
+  /**
+   * 将字符串转义为可安全嵌入 HTML 的实体文本。
+   *
+   * 处理规则：
+   * - `&`、`<`、`>`、`"`、`'` 会被替换为对应实体；
+   * - 其余字符（中文、字母、数字、换行、空白等）原样保留；
+   * - 空字符串返回空字符串。
+   *
+   * 边界与意外场景：
+   * - 已转义文本会被二次转义（如 `&lt;` → `&amp;lt;`），调用方需自行保证
+   *   同一段文本只转义一次。
+   *
+   * @param html 待转义的原始字符串。
+   * @returns 转义后的字符串。
+   *
+   * @example
+   * new XHtml().escape('<a href="x">') // '&lt;a href=&quot;x&quot;&gt;'
+   * new XHtml().escape('') // ''
+   */
+  static escape(html: string): string;
+  /**
+   * 将 HTML 实体还原为原始字符。
+   *
+   * 处理规则：
+   * - 还原 `&amp;`、`&lt;`、`&gt;`、`&quot;`、`&#39;`、`&apos;`；
+   * - 未匹配到上述实体的文本原样保留；
+   * - 空字符串返回空字符串。
+   *
+   * 边界与意外场景：
+   * - `&nbsp;`、`&copy;` 等其它命名实体不会被还原；
+   * - `&#65;`、`&#x41;` 等数字实体不会被还原；
+   * - 反转义是一次性替换而非循环展开，例如 `&amp;amp;` 还原后得到 `&amp;`
+   *   而不会继续还原成 `&`。
+   *
+   * @param html 含 HTML 实体的字符串。
+   * @returns 还原后的字符串。
+   *
+   * @example
+   * new XHtml().unescape('&lt;a&amp;b&gt;') // '<a&b>'
+   * new XHtml().unescape('&apos;ok&apos;') // "'ok'"
+   * new XHtml().unescape('') // ''
+   */
+  static unescape(html: string): string;
+  /**
+   * 将 HTML 字符串解析为可查询的节点树。
+   *
+   * 基于 `node-html-parser` 实现，返回的根节点是一个“文档容器”：
+   * - 根节点自身不携带标签名（`tagName` / `rawTagName` 为 `null`），
+   *   真正解析出的元素位于 `childNodes` 中；
+   * - 同时支持完整文档与 HTML 片段（多个顶层节点）；
+   * - 元素节点与文本节点会被保留，注释节点默认被丢弃；
+   * - 属性可通过 `getAttribute` / `rawAttributes` 读取，元素可通过
+   *   `querySelector` / `querySelectorAll` / `getElementById` /
+   *   `getElementsByTagName` 等方法查询。
+   *
+   * 边界与意外场景：
+   * - 空字符串解析为空树（`childNodes` 为空、`textContent` 为空字符串）；
+   * - 查询不到匹配元素时，选择器方法返回 `null` / 空数组，而不会抛出异常；
+   * - 本方法不负责 HTML 清理与消毒，不可信输入需先经过 `escape` 或其它
+   *   消毒流程后再使用；
+   * - 底层解析失败时会直接抛出异常，本方法不做兜底转换。
+   *
+   * @param html 待解析的 HTML 字符串。
+   * @returns 解析得到的根节点（HTMLElement），其子节点为实际解析出的元素。
+   *
+   * @example
+   * const root = new XHtml().parse('<div class="box">hi<span>!</span></div>');
+   * root.querySelector('.box')?.textContent // 'hi!'
+   * root.querySelectorAll('span').length // 1
+   */
+  static parse(html: string): HTMLElement;
+}

package/lib/html.mjs

@@ -0,0 +1,112 @@
+import { parse } from "node-html-parser";
+import { escapeHTML, unescapeHTML } from "fast-escape-html";
+// src/html.ts
+/**
+* HTML 转义与反转义工具。
+*
+* 基于 `fast-escape-html` 实现，用于在把不可信文本嵌入 HTML 前进行转义，
+* 或将已转义的 HTML 实体还原为原始字符，避免标签错乱与 XSS 注入。
+*
+* 转义字符对照：
+* | 原字符 | 转义结果 |
+* | ------ | -------- |
+* | `&`    | `&`  |
+* | `<`    | `&lt;`   |
+* | `>`    | `&gt;`   |
+* | `"`    | `&quot;` |
+* | `'`    | `&#39;`  |
+*
+* @example
+* const html = new XHtml();
+* html.escape('<a href="x">\'</a>') // '&lt;a href=&quot;x&quot;&gt;&#39;&lt;/a&gt;'
+* html.unescape('&lt;a&amp;b&gt;') // '<a&b>'
+*
+* @remarks
+* - `escape` 是无状态转义：已含实体的文本会再次被转义（如 `&lt;` →
+*   `&amp;lt;`），因此不要对同一段文本重复调用；
+* - `unescape` 只还原本工具转义出的实体（`&amp;`、`&lt;`、`&gt;`、
+*   `&quot;`、`&#39;`、`&apos;`），不处理 `&nbsp;`、`&copy;` 等其它命名
+*   实体，也不处理 `&#65;`、`&#x41;` 这类十进制/十六进制数字实体；
+* - 本工具面向 HTML 文本节点/属性值的转义场景，不负责 URL 编码，也不保证
+*   脚本、样式等非 HTML 上下文的安全。
+*/
+var XHtml = class {
+	/**
+	* 将字符串转义为可安全嵌入 HTML 的实体文本。
+	*
+	* 处理规则：
+	* - `&`、`<`、`>`、`"`、`'` 会被替换为对应实体；
+	* - 其余字符（中文、字母、数字、换行、空白等）原样保留；
+	* - 空字符串返回空字符串。
+	*
+	* 边界与意外场景：
+	* - 已转义文本会被二次转义（如 `&lt;` → `&amp;lt;`），调用方需自行保证
+	*   同一段文本只转义一次。
+	*
+	* @param html 待转义的原始字符串。
+	* @returns 转义后的字符串。
+	*
+	* @example
+	* new XHtml().escape('<a href="x">') // '&lt;a href=&quot;x&quot;&gt;'
+	* new XHtml().escape('') // ''
+	*/
+	static escape(html) {
+		return escapeHTML(html);
+	}
+	/**
+	* 将 HTML 实体还原为原始字符。
+	*
+	* 处理规则：
+	* - 还原 `&amp;`、`&lt;`、`&gt;`、`&quot;`、`&#39;`、`&apos;`；
+	* - 未匹配到上述实体的文本原样保留；
+	* - 空字符串返回空字符串。
+	*
+	* 边界与意外场景：
+	* - `&nbsp;`、`&copy;` 等其它命名实体不会被还原；
+	* - `&#65;`、`&#x41;` 等数字实体不会被还原；
+	* - 反转义是一次性替换而非循环展开，例如 `&amp;amp;` 还原后得到 `&amp;`
+	*   而不会继续还原成 `&`。
+	*
+	* @param html 含 HTML 实体的字符串。
+	* @returns 还原后的字符串。
+	*
+	* @example
+	* new XHtml().unescape('&lt;a&amp;b&gt;') // '<a&b>'
+	* new XHtml().unescape('&apos;ok&apos;') // "'ok'"
+	* new XHtml().unescape('') // ''
+	*/
+	static unescape(html) {
+		return unescapeHTML(html);
+	}
+	/**
+	* 将 HTML 字符串解析为可查询的节点树。
+	*
+	* 基于 `node-html-parser` 实现，返回的根节点是一个“文档容器”：
+	* - 根节点自身不携带标签名（`tagName` / `rawTagName` 为 `null`），
+	*   真正解析出的元素位于 `childNodes` 中；
+	* - 同时支持完整文档与 HTML 片段（多个顶层节点）；
+	* - 元素节点与文本节点会被保留，注释节点默认被丢弃；
+	* - 属性可通过 `getAttribute` / `rawAttributes` 读取，元素可通过
+	*   `querySelector` / `querySelectorAll` / `getElementById` /
+	*   `getElementsByTagName` 等方法查询。
+	*
+	* 边界与意外场景：
+	* - 空字符串解析为空树（`childNodes` 为空、`textContent` 为空字符串）；
+	* - 查询不到匹配元素时，选择器方法返回 `null` / 空数组，而不会抛出异常；
+	* - 本方法不负责 HTML 清理与消毒，不可信输入需先经过 `escape` 或其它
+	*   消毒流程后再使用；
+	* - 底层解析失败时会直接抛出异常，本方法不做兜底转换。
+	*
+	* @param html 待解析的 HTML 字符串。
+	* @returns 解析得到的根节点（HTMLElement），其子节点为实际解析出的元素。
+	*
+	* @example
+	* const root = new XHtml().parse('<div class="box">hi<span>!</span></div>');
+	* root.querySelector('.box')?.textContent // 'hi!'
+	* root.querySelectorAll('span').length // 1
+	*/
+	static parse(html) {
+		return parse(html);
+	}
+};
+export { XHtml };

package/lib/json.d.mts

@@ -0,0 +1,50 @@
+/**
+ * JSON 文本与文件读写工具。
+ *
+ * 提供两类能力：
+ * - 严格方法：`parse` / `read`，遇到非法 JSON 或文件异常时抛错；
+ * - 安全方法：`safeParse` / `safeRead`，遇到异常时返回 `undefined`，适合可选配置读取场景。
+ */
+export declare class XJson {
+  /**
+   * 严格解析 JSON 文本。
+   *
+   * - 解析成功：返回目标类型值；
+   * - 解析失败：抛出 `SyntaxError`。
+   */
+  static parse<T>(value: string): T;
+  /**
+   * 安全解析 JSON 文本。
+   *
+   * - 解析成功：返回目标类型值；
+   * - 解析失败：返回 `undefined`。
+   *
+   * 适用于“配置可缺省、失败可兜底”的场景，例如从环境变量读取可选 JSON。
+   */
+  static safeParse<T>(value: string): T | undefined;
+  /**
+   * 序列化为 JSON 字符串。
+   *
+   * @param compact `true` 时输出紧凑格式（无缩进）；`false`（默认）时输出 2 空格缩进，便于阅读与 git diff。
+   */
+  static stringify(value: unknown, compact?: boolean): string;
+  /**
+   * 严格读取并解析 JSON 文件（UTF-8）。
+   *
+   * 读取失败（如文件不存在）或解析失败时会抛错。
+   */
+  static read<T>(file: string): Promise<T>;
+  /**
+   * 安全读取并解析 JSON 文件（UTF-8）。
+   *
+   * - 文件不存在、权限问题、JSON 非法等任意异常：返回 `undefined`；
+   * - 读取和解析都成功：返回目标类型值。
+   *
+   * 适合读取“可选存在”的本地缓存、临时状态文件。
+   */
+  static safeRead<T>(file: string): Promise<T | undefined>;
+  /**
+   * 将值写入 JSON 文件（UTF-8）。
+   */
+  static write(file: string, value: unknown, compact?: boolean): Promise<void>;
+}

package/lib/json.mjs

@@ -0,0 +1,74 @@
+import * as fs from "node:fs";
+// src/json.ts
+/**
+* JSON 文本与文件读写工具。
+*
+* 提供两类能力：
+* - 严格方法：`parse` / `read`，遇到非法 JSON 或文件异常时抛错；
+* - 安全方法：`safeParse` / `safeRead`，遇到异常时返回 `undefined`，适合可选配置读取场景。
+*/
+var XJson = class XJson {
+	/**
+	* 严格解析 JSON 文本。
+	*
+	* - 解析成功：返回目标类型值；
+	* - 解析失败：抛出 `SyntaxError`。
+	*/
+	static parse(value) {
+		return JSON.parse(value);
+	}
+	/**
+	* 安全解析 JSON 文本。
+	*
+	* - 解析成功：返回目标类型值；
+	* - 解析失败：返回 `undefined`。
+	*
+	* 适用于“配置可缺省、失败可兜底”的场景，例如从环境变量读取可选 JSON。
+	*/
+	static safeParse(value) {
+		try {
+			return XJson.parse(value);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* 序列化为 JSON 字符串。
+	*
+	* @param compact `true` 时输出紧凑格式（无缩进）；`false`（默认）时输出 2 空格缩进，便于阅读与 git diff。
+	*/
+	static stringify(value, compact = false) {
+		return JSON.stringify(value, null, compact ? void 0 : 2);
+	}
+	/**
+	* 严格读取并解析 JSON 文件（UTF-8）。
+	*
+	* 读取失败（如文件不存在）或解析失败时会抛错。
+	*/
+	static async read(file) {
+		const value = await fs.promises.readFile(file, "utf8");
+		return XJson.parse(value);
+	}
+	/**
+	* 安全读取并解析 JSON 文件（UTF-8）。
+	*
+	* - 文件不存在、权限问题、JSON 非法等任意异常：返回 `undefined`；
+	* - 读取和解析都成功：返回目标类型值。
+	*
+	* 适合读取“可选存在”的本地缓存、临时状态文件。
+	*/
+	static async safeRead(file) {
+		try {
+			return await XJson.read(file);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* 将值写入 JSON 文件（UTF-8）。
+	*/
+	static async write(file, value, compact = false) {
+		await fs.promises.writeFile(file, XJson.stringify(value, compact));
+	}
+};
+export { XJson };

package/lib/jwt.d.mts

@@ -0,0 +1,128 @@
+import { MsValue } from "vtils";
+import jwt from "jsonwebtoken";
+import { LRUCache } from "lru-cache";
+import { RequiredBy } from "vtils/types";
+import { IncomingHttpHeaders } from "node:http";
+/**
+ * JWT 载荷。
+ *
+ * 即签入 token 的自定义数据；`jsonwebtoken` 签发时会额外写入
+ * `iat`（签发时间，Unix 秒）与 `exp`（过期时间，Unix 秒）两个标准字段。
+ *
+ * 该接口只是宽松约束，实际载荷可包含任意字段，
+ * 调用方通过 `sign` / `verify` 的泛型参数指定具体形状。
+ */
+export interface XJwtPayload extends Record<string, any> {}
+/**
+ * `XJwt` 的构造选项。
+ */
+export interface XJwtOptions {
+  /**
+   * 签名密钥。
+   *
+   * 用于签发与校验 token，必须保密；一旦泄露，
+   * 任何人都可以伪造出能被校验通过的 token。
+   */
+  secret: string;
+  /**
+   * 默认有效期。
+   *
+   * 支持字符串（如 `'1s'`、`'30m'`、`'7d'`）或数字（毫秒）。
+   * 当 `sign` 未显式传入 `ttl` 时使用该值。
+   *
+   * 说明：token 的 `exp` 字段精度为秒（`jsonwebtoken` 的限制），
+   * 换算时不足 1 秒的部分会四舍五入；缓存的有效期则使用毫秒精度。
+   */
+  ttl: MsValue;
+  /**
+   * 可选的内存缓存配置。
+   *
+   * 传入后启用“先查缓存、命中即返回”的快速校验路径，
+   * 可避免对同一 token 重复执行 `jsonwebtoken` 验签。
+   */
+  cache?: LRUCache.Options<string, XJwtPayload, any>;
+  /**
+   * 校验通过后的钩子。
+   *
+   * 在 token 校验成功（或命中缓存）后、`verify` 返回前调用，
+   * 可用于记录日志、更新活跃状态等；若钩子抛出异常，
+   * `verify` 会以该异常拒绝。
+   */
+  onVerify?: (payload: XJwtPayload & RequiredBy<jwt.JwtPayload, 'iat' | 'exp'> & {
+    token: string;
+  }) => any;
+}
+/**
+ * `XJwt.verify` 的返回结果。
+ *
+ * 在自定义载荷的基础上，合并 `jsonwebtoken` 校验后的标准字段
+ * （`iat` / `exp` 等）以及本次校验所用的 `token` 字段。
+ */
+export type XJwtVerifyResult<T extends XJwtPayload> = T & RequiredBy<jwt.JwtPayload, 'iat' | 'exp'> & {
+  token: string;
+};
+/**
+ * JWT 签发与校验工具。
+ *
+ * 封装 `jsonwebtoken`，提供统一的签发（`sign`）与校验（`verify`），
+ * 并额外支持：
+ * - 可选的内存缓存（`LRUCache`），命中缓存时跳过重复验签；
+ * - 从 HTTP 或 WebSocket 升级请求头中提取 token（`verifyFromHttpHeaders`）。
+ *
+ * @example
+ * const xJwt = new XJwt({ secret: 'xx', ttl: '1h' });
+ *
+ * const token = xJwt.sign({ userId: 1 });
+ * // 'header.payload.signature'
+ *
+ * await xJwt.verify(token);
+ * // { userId: 1, iat: 1730000000, exp: 1730003600, token: 'header.payload.signature' }
+ */
+export declare class XJwt {
+  private options;
+  private cache;
+  constructor(options: XJwtOptions);
+  /**
+   * 签发 JWT。
+   *
+   * 使用 `secret` 对 `payload` 签名，并写入 `iat` 与 `exp`。
+   * 若启用了缓存，会将原始 `payload` 以 token 为 key 写入缓存，
+   * 有效期与 token 一致，供 `verify` 快速命中。
+   *
+   * @param payload 要签入 token 的自定义载荷。
+   * @param ttl 有效期，默认使用构造时传入的 `options.ttl`；
+   *            支持字符串（如 `'1s'`）或数字（毫秒）。
+   * @returns 签名后的 JWT 字符串。
+   */
+  sign<T extends XJwtPayload>(payload: T, ttl?: MsValue): string;
+  /**
+   * 校验 JWT。
+   *
+   * 主要分支：
+   * - 启用了缓存且 token 命中缓存：直接返回缓存中的载荷（补上 `token` 字段），
+   *   不再执行验签；
+   * - 否则调用 `jsonwebtoken.verify` 验签，要求载荷中存在 `iat` 与 `exp`
+   *   且未过期；验签通过后写入缓存（有效期 = token 剩余时长）并返回。
+   *
+   * 校验通过后，会先执行 `options.onVerify`（若已配置），再返回结果。
+   *
+   * @param token 待校验的 JWT 字符串。
+   * @returns 载荷与 `token` 字段合并后的对象（含 `iat` / `exp` 等标准字段）。
+   * @throws 当 token 无效、格式错误、已过期，或 `onVerify` 钩子抛出异常时拒绝。
+   */
+  verify<T extends XJwtPayload>(token: string): Promise<XJwtVerifyResult<T>>;
+  /**
+   * 从请求头中提取 token 并校验。
+   *
+   * 依次尝试以下来源：
+   * 1. `authorization` 头：支持 `Bearer <token>` 形式，也兼容不带 scheme 的
+   *    原始 token（按空格拆分后，若只有一段则直接作为 token）；
+   * 2. `sec-websocket-protocol` 头（WebSocket 升级请求）：其值为原始 token，
+   *    会被包装成 `Bearer <token>` 后按相同逻辑解析。
+   *
+   * @param headers Node HTTP 请求头对象。
+   * @returns `verify` 的校验结果。
+   * @throws 当两个头都缺失或为空时抛出异常。
+   */
+  verifyFromHttpHeaders<T extends XJwtPayload>(headers: IncomingHttpHeaders): Promise<XJwtVerifyResult<T>>;
+}

package/lib/jwt.mjs

@@ -0,0 +1,104 @@
+import { ms } from "vtils";
+import { differenceInMilliseconds, fromUnixTime } from "vtils/date";
+import jwt from "jsonwebtoken";
+import { LRUCache } from "lru-cache";
+// src/jwt.ts
+/**
+* JWT 签发与校验工具。
+*
+* 封装 `jsonwebtoken`，提供统一的签发（`sign`）与校验（`verify`），
+* 并额外支持：
+* - 可选的内存缓存（`LRUCache`），命中缓存时跳过重复验签；
+* - 从 HTTP 或 WebSocket 升级请求头中提取 token（`verifyFromHttpHeaders`）。
+*
+* @example
+* const xJwt = new XJwt({ secret: 'xx', ttl: '1h' });
+*
+* const token = xJwt.sign({ userId: 1 });
+* // 'header.payload.signature'
+*
+* await xJwt.verify(token);
+* // { userId: 1, iat: 1730000000, exp: 1730003600, token: 'header.payload.signature' }
+*/
+var XJwt = class {
+	options;
+	cache;
+	constructor(options) {
+		this.options = options;
+		if (options.cache) this.cache = new LRUCache(options.cache);
+	}
+	/**
+	* 签发 JWT。
+	*
+	* 使用 `secret` 对 `payload` 签名，并写入 `iat` 与 `exp`。
+	* 若启用了缓存，会将原始 `payload` 以 token 为 key 写入缓存，
+	* 有效期与 token 一致，供 `verify` 快速命中。
+	*
+	* @param payload 要签入 token 的自定义载荷。
+	* @param ttl 有效期，默认使用构造时传入的 `options.ttl`；
+	*            支持字符串（如 `'1s'`）或数字（毫秒）。
+	* @returns 签名后的 JWT 字符串。
+	*/
+	sign(payload, ttl = this.options.ttl) {
+		const token = jwt.sign(payload, this.options.secret, { expiresIn: ms(ttl, true) });
+		if (this.cache) this.cache.set(token, payload, { ttl: ms(ttl) });
+		return token;
+	}
+	/**
+	* 校验 JWT。
+	*
+	* 主要分支：
+	* - 启用了缓存且 token 命中缓存：直接返回缓存中的载荷（补上 `token` 字段），
+	*   不再执行验签；
+	* - 否则调用 `jsonwebtoken.verify` 验签，要求载荷中存在 `iat` 与 `exp`
+	*   且未过期；验签通过后写入缓存（有效期 = token 剩余时长）并返回。
+	*
+	* 校验通过后，会先执行 `options.onVerify`（若已配置），再返回结果。
+	*
+	* @param token 待校验的 JWT 字符串。
+	* @returns 载荷与 `token` 字段合并后的对象（含 `iat` / `exp` 等标准字段）。
+	* @throws 当 token 无效、格式错误、已过期，或 `onVerify` 钩子抛出异常时拒绝。
+	*/
+	async verify(token) {
+		const data = await new Promise((resolve, reject) => {
+			if (this.cache && this.cache.has(token)) {
+				resolve({
+					...this.cache.get(token),
+					token
+				});
+				return;
+			}
+			jwt.verify(token, this.options.secret, { ignoreExpiration: false }, (err, decoded) => {
+				if (err || !decoded || typeof decoded === "string" || !decoded.iat || !decoded.exp) {
+					reject(/* @__PURE__ */ new Error("JWT 校验失败：token 无效、格式错误或已过期"));
+					return;
+				}
+				decoded.token = token;
+				if (this.cache) this.cache.set(token, decoded, { ttl: differenceInMilliseconds(fromUnixTime(decoded.exp), /* @__PURE__ */ new Date()) });
+				resolve(decoded);
+			});
+		});
+		await this.options.onVerify?.(data);
+		return data;
+	}
+	/**
+	* 从请求头中提取 token 并校验。
+	*
+	* 依次尝试以下来源：
+	* 1. `authorization` 头：支持 `Bearer <token>` 形式，也兼容不带 scheme 的
+	*    原始 token（按空格拆分后，若只有一段则直接作为 token）；
+	* 2. `sec-websocket-protocol` 头（WebSocket 升级请求）：其值为原始 token，
+	*    会被包装成 `Bearer <token>` 后按相同逻辑解析。
+	*
+	* @param headers Node HTTP 请求头对象。
+	* @returns `verify` 的校验结果。
+	* @throws 当两个头都缺失或为空时抛出异常。
+	*/
+	async verifyFromHttpHeaders(headers) {
+		const authorization = headers.authorization || headers["sec-websocket-protocol"] && `Bearer ${headers["sec-websocket-protocol"]}` || "";
+		if (!authorization) throw new Error("缺少认证信息：请提供 Authorization 或 Sec-WebSocket-Protocol 请求头");
+		const [scheme, token = scheme] = authorization.split(" ");
+		return this.verify(token);
+	}
+};
+export { XJwt };