@fast-china/utils 1.0.38 → 2.0.2

package/dist/color/index.d.mts

@@ -0,0 +1,90 @@
+//#region src/color/index.d.ts
+/** 0 至 255 范围的 RGB 颜色。 */
+interface RgbColor {
+  /** 蓝色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  blue: number;
+  /** 绿色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  green: number;
+  /** 红色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  red: number;
+}
+/** 带 0 至 1 Alpha 通道的 RGB 颜色。 */
+interface RgbaColor extends RgbColor {
+  /** 不透明度；必须是闭区间 `[0, 1]` 内的有限数，`0` 完全透明，`1` 完全不透明。 */
+  alpha: number;
+}
+/**
+ * 解析可带可不带 `#` 的 `rgb`、`rgba`、`rrggbb` 或 `rrggbbaa`。
+ *
+ * @param value - 十六进制颜色文本。
+ * @returns 标准化的 RGBA 对象；省略 Alpha 时为 1。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+declare function parseHexColor(value: string): RgbaColor;
+/**
+ * 把 RGB 或 RGBA 对象格式化为小写十六进制颜色。
+ *
+ * @param color - 颜色通道；RGB 会四舍五入到最近整数。
+ * @param includeAlpha - 是否输出 Alpha；默认只在传入 Alpha 且小于 1 时输出。
+ * @returns 小写 `#rrggbb` 或 `#rrggbbaa` 文本。
+ * @throws 通道或 Alpha 非法时抛出 `RangeError`。
+ */
+declare function formatHexColor(color: RgbColor | RgbaColor, includeAlpha?: boolean): string;
+/**
+ * 线性混合两种十六进制颜色，包括 Alpha 通道。
+ *
+ * @param first - `amount = 0` 时的颜色。
+ * @param second - `amount = 1` 时的颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 小写十六进制颜色；任一输入含透明度时保留 Alpha。
+ * @throws 颜色非法时抛出 `TypeError`；比例非法时抛出 `RangeError`。
+ */
+declare function mixHexColors(first: string, second: string, amount: number): string;
+/**
+ * 按比例向黑色混合。
+ *
+ * @param color - 合法十六进制颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 混入黑色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+ */
+declare function mixHexColorWithBlack(color: string, amount: number): string;
+/**
+ * 按比例向白色混合。
+ *
+ * @param color - 合法十六进制颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 混入白色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+ */
+declare function mixHexColorWithWhite(color: string, amount: number): string;
+/**
+ * 计算 WCAG sRGB 相对亮度。
+ *
+ * @remarks Alpha 通道不会参与计算；半透明颜色应先与实际背景混合。
+ * @param color - 合法十六进制颜色。
+ * @returns 0 至 1 的相对亮度。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+declare function relativeLuminance(color: string): number;
+/**
+ * 计算两种不透明颜色的 WCAG 对比度，范围 1 至 21。
+ *
+ * @remarks 返回比值本身，不代表特定字号或 WCAG 等级必然通过。
+ * @param first - 第一种十六进制颜色。
+ * @param second - 第二种十六进制颜色。
+ * @returns 较亮颜色与较暗颜色的对比度。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+declare function contrastRatio(first: string, second: string): number;
+/**
+ * 从两个候选颜色中选择与背景对比度更高的一项。
+ *
+ * @param background - 实际不透明背景色。
+ * @param first - 第一候选，默认黑色。
+ * @param second - 第二候选，默认白色。
+ * @returns 对比度较高的原始候选字符串；相同时返回 `first`。
+ * @throws 任一颜色非法时抛出 `TypeError`。
+ */
+declare function pickHigherContrastColor(background: string, first?: string, second?: string): string;
+//#endregion
+export { RgbColor, RgbaColor, contrastRatio, formatHexColor, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, parseHexColor, pickHigherContrastColor, relativeLuminance };
+//# sourceMappingURL=index.d.mts.map

package/dist/color/index.mjs

@@ -0,0 +1,178 @@
+//#region src/color/index.ts
+/**
+* 校验 RGB 颜色通道。
+*
+* @param value - 待校验通道值。
+* @param channel - 用于错误消息的通道名称。
+* @throws `RangeError` 当值非有限或超出 0 至 255。
+*/
+const assertRgbChannel = (value, channel) => {
+	if (!Number.isFinite(value) || value < 0 || value > 255) throw new RangeError(`${channel} must be a finite number from 0 through 255.`);
+};
+/**
+* 校验透明度通道。
+*
+* @param value - 待校验 Alpha 值。
+* @throws `RangeError` 当值非有限或超出闭区间 `[0, 1]`。
+*/
+const assertAlpha = (value) => {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw new RangeError("alpha must be a finite number from 0 through 1.");
+};
+/**
+* 规范化十六进制颜色文本。
+*
+* @param value - 可带 `#` 的 3、4、6 或 8 位颜色文本。
+* @returns 不带 `#` 的 6 或 8 位文本。
+* @throws `TypeError` 当长度或字符不符合十六进制颜色格式。
+*/
+const normalizeHexColor = (value) => {
+	const normalized = value.startsWith("#") ? value.slice(1) : value;
+	if (![
+		3,
+		4,
+		6,
+		8
+	].includes(normalized.length) || !/^[\dA-F]+$/iu.test(normalized)) throw new TypeError("Expected a 3, 4, 6, or 8 digit hexadecimal color.");
+	return normalized.length <= 4 ? Array.from(normalized, (character) => `${character}${character}`).join("") : normalized;
+};
+/**
+* 格式化单个颜色通道。
+*
+* @param value - 已校验的 0 至 255 通道值。
+* @returns 舍入后的两位小写十六进制文本。
+*/
+const formatHexChannel = (value) => Math.round(value).toString(16).padStart(2, "0");
+/**
+* 解析可带可不带 `#` 的 `rgb`、`rgba`、`rrggbb` 或 `rrggbbaa`。
+*
+* @param value - 十六进制颜色文本。
+* @returns 标准化的 RGBA 对象；省略 Alpha 时为 1。
+* @throws 输入非法时抛出 `TypeError`。
+*/
+function parseHexColor(value) {
+	const normalized = normalizeHexColor(value);
+	return {
+		red: Number.parseInt(normalized.slice(0, 2), 16),
+		green: Number.parseInt(normalized.slice(2, 4), 16),
+		blue: Number.parseInt(normalized.slice(4, 6), 16),
+		alpha: normalized.length === 8 ? Number.parseInt(normalized.slice(6, 8), 16) / 255 : 1
+	};
+}
+/**
+* 把 RGB 或 RGBA 对象格式化为小写十六进制颜色。
+*
+* @param color - 颜色通道；RGB 会四舍五入到最近整数。
+* @param includeAlpha - 是否输出 Alpha；默认只在传入 Alpha 且小于 1 时输出。
+* @returns 小写 `#rrggbb` 或 `#rrggbbaa` 文本。
+* @throws 通道或 Alpha 非法时抛出 `RangeError`。
+*/
+function formatHexColor(color, includeAlpha = "alpha" in color && color.alpha < 1) {
+	assertRgbChannel(color.red, "red");
+	assertRgbChannel(color.green, "green");
+	assertRgbChannel(color.blue, "blue");
+	const alpha = "alpha" in color ? color.alpha : 1;
+	assertAlpha(alpha);
+	return `#${`${formatHexChannel(color.red)}${formatHexChannel(color.green)}${formatHexChannel(color.blue)}`}${includeAlpha ? formatHexChannel(alpha * 255) : ""}`;
+}
+/**
+* 线性混合两种十六进制颜色，包括 Alpha 通道。
+*
+* @param first - `amount = 0` 时的颜色。
+* @param second - `amount = 1` 时的颜色。
+* @param amount - 0 至 1 的混合比例。
+* @returns 小写十六进制颜色；任一输入含透明度时保留 Alpha。
+* @throws 颜色非法时抛出 `TypeError`；比例非法时抛出 `RangeError`。
+*/
+function mixHexColors(first, second, amount) {
+	if (!Number.isFinite(amount) || amount < 0 || amount > 1) throw new RangeError("amount must be a finite number from 0 through 1.");
+	const left = parseHexColor(first);
+	const right = parseHexColor(second);
+	/**
+	* 在单个 RGBA 通道上执行与外层相同权重的线性混合。
+	*
+	* @param start - 第一个颜色的通道值。
+	* @param end - 第二个颜色的通道值。
+	* @returns 按外层 `amount` 线性混合后的通道值。
+	*/
+	const mix = (start, end) => start + (end - start) * amount;
+	return formatHexColor({
+		red: mix(left.red, right.red),
+		green: mix(left.green, right.green),
+		blue: mix(left.blue, right.blue),
+		alpha: mix(left.alpha, right.alpha)
+	}, left.alpha < 1 || right.alpha < 1);
+}
+/**
+* 按比例向黑色混合。
+*
+* @param color - 合法十六进制颜色。
+* @param amount - 0 至 1 的混合比例。
+* @returns 混入黑色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+*/
+function mixHexColorWithBlack(color, amount) {
+	return mixHexColors(color, "#000000", amount);
+}
+/**
+* 按比例向白色混合。
+*
+* @param color - 合法十六进制颜色。
+* @param amount - 0 至 1 的混合比例。
+* @returns 混入白色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+*/
+function mixHexColorWithWhite(color, amount) {
+	return mixHexColors(color, "#ffffff", amount);
+}
+/**
+* 按 WCAG sRGB 转换曲线线性化颜色通道。
+*
+* @param channel - 已校验的 0 至 255 通道值。
+* @returns 0 至 1 的线性光值。
+*/
+const linearizeSrgbChannel = (channel) => {
+	const value = channel / 255;
+	return value <= .04045 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4;
+};
+/**
+* 计算 WCAG sRGB 相对亮度。
+*
+* @remarks Alpha 通道不会参与计算；半透明颜色应先与实际背景混合。
+* @param color - 合法十六进制颜色。
+* @returns 0 至 1 的相对亮度。
+* @throws 输入非法时抛出 `TypeError`。
+*/
+function relativeLuminance(color) {
+	const { red, green, blue } = parseHexColor(color);
+	return .2126 * linearizeSrgbChannel(red) + .7152 * linearizeSrgbChannel(green) + .0722 * linearizeSrgbChannel(blue);
+}
+/**
+* 计算两种不透明颜色的 WCAG 对比度，范围 1 至 21。
+*
+* @remarks 返回比值本身，不代表特定字号或 WCAG 等级必然通过。
+* @param first - 第一种十六进制颜色。
+* @param second - 第二种十六进制颜色。
+* @returns 较亮颜色与较暗颜色的对比度。
+* @throws 输入非法时抛出 `TypeError`。
+*/
+function contrastRatio(first, second) {
+	const firstLuminance = relativeLuminance(first);
+	const secondLuminance = relativeLuminance(second);
+	const lighter = Math.max(firstLuminance, secondLuminance);
+	const darker = Math.min(firstLuminance, secondLuminance);
+	return (lighter + .05) / (darker + .05);
+}
+/**
+* 从两个候选颜色中选择与背景对比度更高的一项。
+*
+* @param background - 实际不透明背景色。
+* @param first - 第一候选，默认黑色。
+* @param second - 第二候选，默认白色。
+* @returns 对比度较高的原始候选字符串；相同时返回 `first`。
+* @throws 任一颜色非法时抛出 `TypeError`。
+*/
+function pickHigherContrastColor(background, first = "#000000", second = "#ffffff") {
+	return contrastRatio(background, first) >= contrastRatio(background, second) ? first : second;
+}
+//#endregion
+export { contrastRatio, formatHexColor, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, parseHexColor, pickHigherContrastColor, relativeLuminance };
+
+//# sourceMappingURL=index.mjs.map

package/dist/color/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/color/index.ts"],"sourcesContent":["/** 0 至 255 范围的 RGB 颜色。 */\nexport interface RgbColor {\n\t/** 蓝色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */\n\tblue: number;\n\t/** 绿色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */\n\tgreen: number;\n\t/** 红色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */\n\tred: number;\n}\n\n/** 带 0 至 1 Alpha 通道的 RGB 颜色。 */\nexport interface RgbaColor extends RgbColor {\n\t/** 不透明度；必须是闭区间 `[0, 1]` 内的有限数，`0` 完全透明，`1` 完全不透明。 */\n\talpha: number;\n}\n\n/**\n * 校验 RGB 颜色通道。\n *\n * @param value - 待校验通道值。\n * @param channel - 用于错误消息的通道名称。\n * @throws `RangeError` 当值非有限或超出 0 至 255。\n */\nconst assertRgbChannel = (value: number, channel: string): void => {\n\tif (!Number.isFinite(value) || value < 0 || value > 255) {\n\t\tthrow new RangeError(`${channel} must be a finite number from 0 through 255.`);\n\t}\n};\n\n/**\n * 校验透明度通道。\n *\n * @param value - 待校验 Alpha 值。\n * @throws `RangeError` 当值非有限或超出闭区间 `[0, 1]`。\n */\nconst assertAlpha = (value: number): void => {\n\tif (!Number.isFinite(value) || value < 0 || value > 1) {\n\t\tthrow new RangeError(\"alpha must be a finite number from 0 through 1.\");\n\t}\n};\n\n/**\n * 规范化十六进制颜色文本。\n *\n * @param value - 可带 `#` 的 3、4、6 或 8 位颜色文本。\n * @returns 不带 `#` 的 6 或 8 位文本。\n * @throws `TypeError` 当长度或字符不符合十六进制颜色格式。\n */\nconst normalizeHexColor = (value: string): string => {\n\tconst normalized = value.startsWith(\"#\") ? value.slice(1) : value;\n\tif (![3, 4, 6, 8].includes(normalized.length) || !/^[\\dA-F]+$/iu.test(normalized)) {\n\t\tthrow new TypeError(\"Expected a 3, 4, 6, or 8 digit hexadecimal color.\");\n\t}\n\treturn normalized.length <= 4 ? Array.from(normalized, (character) => `${character}${character}`).join(\"\") : normalized;\n};\n\n/**\n * 格式化单个颜色通道。\n *\n * @param value - 已校验的 0 至 255 通道值。\n * @returns 舍入后的两位小写十六进制文本。\n */\nconst formatHexChannel = (value: number): string => Math.round(value).toString(16).padStart(2, \"0\");\n\n/**\n * 解析可带可不带 `#` 的 `rgb`、`rgba`、`rrggbb` 或 `rrggbbaa`。\n *\n * @param value - 十六进制颜色文本。\n * @returns 标准化的 RGBA 对象；省略 Alpha 时为 1。\n * @throws 输入非法时抛出 `TypeError`。\n */\nexport function parseHexColor(value: string): RgbaColor {\n\tconst normalized = normalizeHexColor(value);\n\treturn {\n\t\tred: Number.parseInt(normalized.slice(0, 2), 16),\n\t\tgreen: Number.parseInt(normalized.slice(2, 4), 16),\n\t\tblue: Number.parseInt(normalized.slice(4, 6), 16),\n\t\talpha: normalized.length === 8 ? Number.parseInt(normalized.slice(6, 8), 16) / 255 : 1,\n\t};\n}\n\n/**\n * 把 RGB 或 RGBA 对象格式化为小写十六进制颜色。\n *\n * @param color - 颜色通道；RGB 会四舍五入到最近整数。\n * @param includeAlpha - 是否输出 Alpha；默认只在传入 Alpha 且小于 1 时输出。\n * @returns 小写 `#rrggbb` 或 `#rrggbbaa` 文本。\n * @throws 通道或 Alpha 非法时抛出 `RangeError`。\n */\nexport function formatHexColor(color: RgbColor | RgbaColor, includeAlpha: boolean = \"alpha\" in color && color.alpha < 1): string {\n\tassertRgbChannel(color.red, \"red\");\n\tassertRgbChannel(color.green, \"green\");\n\tassertRgbChannel(color.blue, \"blue\");\n\tconst alpha = \"alpha\" in color ? color.alpha : 1;\n\tassertAlpha(alpha);\n\tconst rgb = `${formatHexChannel(color.red)}${formatHexChannel(color.green)}${formatHexChannel(color.blue)}`;\n\treturn `#${rgb}${includeAlpha ? formatHexChannel(alpha * 255) : \"\"}`;\n}\n\n/**\n * 线性混合两种十六进制颜色，包括 Alpha 通道。\n *\n * @param first - `amount = 0` 时的颜色。\n * @param second - `amount = 1` 时的颜色。\n * @param amount - 0 至 1 的混合比例。\n * @returns 小写十六进制颜色；任一输入含透明度时保留 Alpha。\n * @throws 颜色非法时抛出 `TypeError`；比例非法时抛出 `RangeError`。\n */\nexport function mixHexColors(first: string, second: string, amount: number): string {\n\tif (!Number.isFinite(amount) || amount < 0 || amount > 1) {\n\t\tthrow new RangeError(\"amount must be a finite number from 0 through 1.\");\n\t}\n\tconst left = parseHexColor(first);\n\tconst right = parseHexColor(second);\n\t/**\n\t * 在单个 RGBA 通道上执行与外层相同权重的线性混合。\n\t *\n\t * @param start - 第一个颜色的通道值。\n\t * @param end - 第二个颜色的通道值。\n\t * @returns 按外层 `amount` 线性混合后的通道值。\n\t */\n\tconst mix = (start: number, end: number): number => start + (end - start) * amount;\n\treturn formatHexColor(\n\t\t{\n\t\t\tred: mix(left.red, right.red),\n\t\t\tgreen: mix(left.green, right.green),\n\t\t\tblue: mix(left.blue, right.blue),\n\t\t\talpha: mix(left.alpha, right.alpha),\n\t\t},\n\t\tleft.alpha < 1 || right.alpha < 1\n\t);\n}\n\n/**\n * 按比例向黑色混合。\n *\n * @param color - 合法十六进制颜色。\n * @param amount - 0 至 1 的混合比例。\n * @returns 混入黑色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。\n */\nexport function mixHexColorWithBlack(color: string, amount: number): string {\n\treturn mixHexColors(color, \"#000000\", amount);\n}\n\n/**\n * 按比例向白色混合。\n *\n * @param color - 合法十六进制颜色。\n * @param amount - 0 至 1 的混合比例。\n * @returns 混入白色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。\n */\nexport function mixHexColorWithWhite(color: string, amount: number): string {\n\treturn mixHexColors(color, \"#ffffff\", amount);\n}\n\n/**\n * 按 WCAG sRGB 转换曲线线性化颜色通道。\n *\n * @param channel - 已校验的 0 至 255 通道值。\n * @returns 0 至 1 的线性光值。\n */\nconst linearizeSrgbChannel = (channel: number): number => {\n\tconst value = channel / 255;\n\treturn value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;\n};\n\n/**\n * 计算 WCAG sRGB 相对亮度。\n *\n * @remarks Alpha 通道不会参与计算；半透明颜色应先与实际背景混合。\n * @param color - 合法十六进制颜色。\n * @returns 0 至 1 的相对亮度。\n * @throws 输入非法时抛出 `TypeError`。\n */\nexport function relativeLuminance(color: string): number {\n\tconst { red, green, blue } = parseHexColor(color);\n\treturn 0.2126 * linearizeSrgbChannel(red) + 0.7152 * linearizeSrgbChannel(green) + 0.0722 * linearizeSrgbChannel(blue);\n}\n\n/**\n * 计算两种不透明颜色的 WCAG 对比度，范围 1 至 21。\n *\n * @remarks 返回比值本身，不代表特定字号或 WCAG 等级必然通过。\n * @param first - 第一种十六进制颜色。\n * @param second - 第二种十六进制颜色。\n * @returns 较亮颜色与较暗颜色的对比度。\n * @throws 输入非法时抛出 `TypeError`。\n */\nexport function contrastRatio(first: string, second: string): number {\n\tconst firstLuminance = relativeLuminance(first);\n\tconst secondLuminance = relativeLuminance(second);\n\tconst lighter = Math.max(firstLuminance, secondLuminance);\n\tconst darker = Math.min(firstLuminance, secondLuminance);\n\treturn (lighter + 0.05) / (darker + 0.05);\n}\n\n/**\n * 从两个候选颜色中选择与背景对比度更高的一项。\n *\n * @param background - 实际不透明背景色。\n * @param first - 第一候选，默认黑色。\n * @param second - 第二候选，默认白色。\n * @returns 对比度较高的原始候选字符串；相同时返回 `first`。\n * @throws 任一颜色非法时抛出 `TypeError`。\n */\nexport function pickHigherContrastColor(background: string, first = \"#000000\", second = \"#ffffff\"): string {\n\treturn contrastRatio(background, first) >= contrastRatio(background, second) ? first : second;\n}\n"],"mappings":"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"}

package/dist/crypto/index.d.mts

@@ -0,0 +1,326 @@
+import "crypto-js/pad-ansix923.js";
+//#region src/crypto/index.d.ts
+/** AES 分组密码模式；与 .NET `CipherMode.CBC` 和 `CipherMode.ECB` 对应。 */
+type AesCipherMode = "CBC" | "ECB";
+/** AES 填充模式；与 .NET `PaddingMode` 中可由 CryptoJS 互操作的成员对应。 */
+type AesPaddingMode = "None" | "PKCS7" | "Zeros" | "ANSIX923" | "ISO10126";
+/** Web Crypto 导出的 PEM 公私钥对。 */
+interface PemKeyPair {
+  /** 未加密的 PKCS#8 PEM 私钥，包含标准 `PRIVATE KEY` 头尾和 64 字符换行。 */
+  privateKey: string;
+  /** SubjectPublicKeyInfo PEM 公钥，包含标准 `PUBLIC KEY` 头尾和 64 字符换行。 */
+  publicKey: string;
+}
+/** 本模块支持的 Web Crypto 椭圆曲线。 */
+type EcNamedCurve = "P-256" | "P-384" | "P-521";
+/**
+ * 生成安全随机字节。
+ *
+ * @param length - 0 至 65,536 的安全整数；上限来自 Web Crypto 单次请求限制。
+ * @returns 新建的 `Uint8Array`。
+ * @throws 参数非法时抛出 `RangeError`；缺少 Web Crypto 时抛出 `Error`。
+ */
+declare function GenerateRandomBytes(length: number): Uint8Array;
+/**
+ * 以不提前退出的方式比较两个字节数组。
+ *
+ * @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
+ * 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
+ * @param left - 第一字节序列。
+ * @param right - 第二字节序列。
+ * @returns 长度和每个字节均相同时返回 `true`。
+ */
+declare function FixedTimeEquals(left: Uint8Array, right: Uint8Array): boolean;
+/**
+ * 计算 MD5 摘要并返回小写十六进制文本。
+ *
+ * @remarks MD5 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+ * @param value - UTF-8 文本。
+ * @returns 32 字符小写十六进制摘要。
+ */
+declare function MD5Encrypt(value: string): string;
+/**
+ * 计算 SHA-1 摘要并返回大写十六进制文本。
+ *
+ * @remarks SHA-1 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+ * @param value - UTF-8 文本。
+ * @returns 40 字符大写十六进制摘要。
+ */
+declare function SHA1Encrypt(value: string): string;
+/**
+ * 计算 SHA-256 摘要。
+ *
+ * @remarks SHA-256 是快速摘要，不适合直接存储或校验密码。
+ * @param value - UTF-8 字符串或原始字节。
+ * @returns 32 字节摘要。
+ * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+declare function SHA256Bytes(value: string): Promise<Uint8Array>;
+/**
+ * 计算 SHA-256 并格式化为十六进制。
+ *
+ * @param value - UTF-8 字符串或原始字节。
+ * @returns 64 字符大写十六进制文本。
+ * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+declare function SHA256Encrypt(value: string): Promise<string>;
+/**
+ * 计算 SHA-384 摘要。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 48 字节摘要。
+ */
+declare function SHA384Bytes(value: string): Promise<Uint8Array>;
+/**
+ * 计算 SHA-384 并格式化为十六进制文本。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 96 个大写十六进制字符组成的摘要。
+ */
+declare function SHA384Encrypt(value: string): Promise<string>;
+/**
+ * 计算 SHA-512 摘要。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 64 字节摘要。
+ */
+declare function SHA512Bytes(value: string): Promise<Uint8Array>;
+/**
+ * 计算 SHA-512 并格式化为十六进制文本。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 128 个大写十六进制字符组成的摘要。
+ */
+declare function SHA512Encrypt(value: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-256 认证文本，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 64 个小写十六进制字符组成的认证标签。
+ */
+declare function HMACSHA256Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-384 认证文本或字节，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 96 个小写十六进制字符组成的认证标签。
+ */
+declare function HMACSHA384Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-512 认证文本或字节，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 128 个小写十六进制字符组成的认证标签。
+ */
+declare function HMACSHA512Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 PBKDF2-HMAC-SHA-256 从密码派生密钥。
+ *
+ * @param password - 1 至 1,024 UTF-8 字节的密码。
+ * @param salt - 至少 8 字节的盐。
+ * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
+ * @param outputLength - 输出长度，范围为 1 至 1,024 字节。
+ * @returns 指定长度的派生密钥。
+ * @throws 参数超过协议边界时抛出 `TypeError` 或 `RangeError`。
+ */
+declare function PBKDF2SHA256(password: string, salt: Uint8Array, iterations?: number, outputLength?: number): Promise<Uint8Array>;
+/**
+ * 生成可持久化的随机盐 PBKDF2-HMAC-SHA-256 密码哈希。
+ *
+ * @param password - 1 至 1,024 UTF-8 字节的密码。
+ * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
+ * @returns 包含版本、迭代次数、16 字节随机盐和 32 字节派生密钥的自描述字符串。
+ */
+declare function HashPasswordPBKDF2SHA256(password: string, iterations?: number): Promise<string>;
+/**
+ * 验证 {@link HashPasswordPBKDF2SHA256} 生成的密码哈希。
+ *
+ * @param password - 要验证的密码。
+ * @param passwordHash - 自描述的 PBKDF2-HMAC-SHA-256 密码哈希。
+ * @returns 格式有效且密码匹配时返回 `true`；格式无效或密码错误时返回 `false`。
+ */
+declare function VerifyPasswordPBKDF2SHA256(password: string, passwordHash: string): Promise<boolean>;
+/**
+ * 使用 RFC 5869 HKDF-SHA-256 派生上下文隔离的密钥材料。
+ *
+ * @param inputKeyMaterial - 输入密钥材料，例如 ECDH 原始共享秘密。
+ * @param salt - 可选盐；空值按 RFC 5869 的零盐语义处理。
+ * @param info - 应用、协议和密钥用途上下文。
+ * @param outputLength - 输出长度，范围为 1 至 8,160 字节。
+ * @returns 与 `salt` 和 `info` 绑定的派生密钥。
+ */
+declare function HKDFSHA256(inputKeyMaterial: Uint8Array, salt?: Uint8Array, info?: Uint8Array, outputLength?: number): Promise<Uint8Array>;
+/**
+ * 使用 AES-256 对 UTF-8 文本进行分组加密。
+ *
+ * @remarks 密钥和 IV 分别补字符 `f` 或截断到 32、16 个 UTF-16 Code Unit，与 .NET
+ * `AESEncrypt` 保持一致。CBC/ECB 不提供完整性认证，密文可能被篡改。
+ * @param dataStr - 要加密的 UTF-8 文本；空白文本返回 `null`。
+ * @param key - 非空白的密钥文本。
+ * @param vector - 非空白的初始化向量文本；ECB 模式仍要求传入该参数以对齐 .NET 签名。
+ * @param cipherMode - AES 分组模式，默认 `CBC`。
+ * @param paddingMode - AES 填充模式，默认 `PKCS7`。
+ * @returns Base64 密文；输入、密钥或 IV 为空白时返回 `null`。
+ * @throws 模式或填充不受支持时抛出 `RangeError`。
+ */
+declare function AESEncrypt(dataStr: string, key: string, vector: string, cipherMode?: AesCipherMode, paddingMode?: AesPaddingMode): string | null;
+/**
+ * 使用 AES-256 解密 Base64 分组密文。
+ *
+ * @remarks 参数归一化规则与 {@link AESEncrypt} 以及 .NET `AESDecrypt` 相同。
+ * @param dataStr - Base64 密文；空白文本返回 `null`。
+ * @param key - 加密时使用的密钥文本。
+ * @param vector - 加密时使用的初始化向量文本。
+ * @param cipherMode - AES 分组模式，默认 `CBC`。
+ * @param paddingMode - AES 填充模式，默认 `PKCS7`。
+ * @returns 解密后的 UTF-8 文本；输入、密钥或 IV 为空白时返回 `null`。
+ * @throws 模式、填充、Base64、密钥或密文无效时抛出错误。
+ */
+declare function AESDecrypt(dataStr: string, key: string, vector: string, cipherMode?: AesCipherMode, paddingMode?: AesPaddingMode): string | null;
+/**
+ * 使用 SHA-256 归一化文本密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
+ *
+ * @remarks 输出与 .NET `AESEncryptAuthenticated` 的 v1 Base64 二进制载荷完全一致。
+ * @param plaintext - 要加密的 UTF-8 文本。
+ * @param key - 非空的 UTF-8 文本密钥；内部归一化为 32 字节 SHA-256 摘要。
+ * @returns Base64 编码的 v1 AES-GCM 认证载荷。
+ * @throws 密钥为空或运行时缺少 Web Crypto 时抛出错误。
+ */
+declare function AESEncryptAuthenticated(plaintext: string, key: string): Promise<string>;
+/**
+ * 解密并认证 .NET `AESEncryptAuthenticated` 或 {@link AESEncryptAuthenticated} 生成的载荷。
+ *
+ * @param payload - Base64 编码的 v1 AES-GCM 二进制载荷。
+ * @param key - 加密时使用的非空 UTF-8 文本密钥。
+ * @returns 通过认证的 UTF-8 明文。
+ * @throws 载荷格式无效、密钥错误或认证失败时抛出错误。
+ */
+declare function AESDecryptAuthenticated(payload: string, key: string): Promise<string>;
+/**
+ * 使用 PBKDF2-HMAC-SHA-256 派生密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
+ *
+ * @remarks 每次调用生成独立 16 字节盐与 12 字节 IV。输出是与 .NET `AESEncryptWithPassword`
+ * 一致的 v2 自描述载荷，不应由业务代码手动拆分或修改。密码加密不替代密钥管理。
+ * @param plaintext - 原始文本，不进行 JSON 推断；UTF-8 编码后最大 8 MiB。
+ * @param password - 1 至 1024 UTF-8 字节的秘密口令。
+ * @param iterations - PBKDF2 工作因子，默认 600,000。
+ * @returns 认证密文字符串；相同输入每次产生不同结果。
+ * @throws 口令非法时抛出 `TypeError` 或 `RangeError`；明文过大时抛出 `RangeError`；
+ * 运行时缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+declare function AESEncryptWithPassword(plaintext: string, password: string, iterations?: number): Promise<string>;
+/**
+ * 解密 {@link AESEncryptWithPassword} 生成的 v2 认证载荷。
+ *
+ * @param payload - 未修改的 v2 载荷，最大约 16 MiB 文本。
+ * @param password - 加密时使用的口令。
+ * @returns 原始 UTF-8 文本。
+ * @throws 格式或字段非法时抛出 `TypeError`，载荷过大时抛出 `RangeError`，认证或密码
+ * 失败及缺少平台能力时抛出 `Error`。
+ */
+declare function AESDecryptWithPassword(payload: string, password: string): Promise<string>;
+/**
+ * 生成可供 RSA-OAEP/SHA-256 与 RSA-PSS/SHA-256 共用的 PEM 密钥对。
+ *
+ * @param modulusLength - RSA 模数位数，默认 2,048；必须是不小于 2,048 的 256 倍数。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ * @throws 模数小于 2,048 或不是 256 的倍数时抛出 `RangeError`。
+ */
+declare function GenerateRSAKeyPair(modulusLength?: number): Promise<PemKeyPair>;
+/**
+ * 使用 RSA-OAEP/SHA-256 公钥加密 UTF-8 文本。
+ *
+ * @param plaintext - 要加密的 UTF-8 文本；长度必须满足 RSA-OAEP 模数限制。
+ * @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+ * @returns Base64 编码的 RSA 密文。
+ * @throws 公钥格式无效或明文超过 RSA-OAEP 容量时抛出错误。
+ */
+declare function RSAEncryptOAEP(plaintext: string, publicKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。
+ *
+ * @param ciphertext - Base64 编码的 RSA 密文。
+ * @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+ * @returns 解密后的 UTF-8 文本。
+ * @throws 私钥、Base64 或密文无效时抛出错误。
+ */
+declare function RSADecryptOAEP(ciphertext: string, privateKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-PSS/SHA-256 私钥签名文本或字节。
+ *
+ * @param value - 要签名的 UTF-8 文本或原始字节。
+ * @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+ * @returns Base64 编码的 RSA-PSS 签名；盐长度固定为 32 字节。
+ * @throws 私钥格式无效或签名失败时抛出错误。
+ */
+declare function RSASignPSS(value: string, privateKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-PSS/SHA-256 公钥验证 Base64 签名。
+ *
+ * @param value - 签名时使用的 UTF-8 文本或原始字节。
+ * @param signature - Base64 编码的 RSA-PSS 签名。
+ * @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+ * @returns 签名与内容、公钥匹配时返回 `true`。
+ * @throws 公钥或 Base64 格式无效时抛出错误。
+ */
+declare function RSAVerifyPSS(value: string, signature: string, publicKeyPem: string): Promise<boolean>;
+/**
+ * 生成 ECDSA PEM 签名密钥对。
+ *
+ * @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ */
+declare function GenerateECDSAKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/**
+ * 使用 ECDSA 私钥签名文本或字节。
+ *
+ * @remarks Web Crypto 返回 IEEE P1363 固定字段拼接格式，与 .NET 实现一致。
+ * @param value - 要签名的 UTF-8 文本或原始字节。
+ * @param privateKeyPem - 未加密的 EC PKCS#8 PEM 私钥。
+ * @param namedCurve - 私钥使用的 NIST 曲线。
+ * @returns Base64 编码的 IEEE P1363 ECDSA 签名。
+ */
+declare function ECDSASign(value: string, privateKeyPem: string, namedCurve?: EcNamedCurve): Promise<string>;
+/**
+ * 使用 ECDSA 公钥验证 Base64 签名。
+ *
+ * @param value - 签名时使用的 UTF-8 文本或原始字节。
+ * @param signature - Base64 编码的 IEEE P1363 ECDSA 签名。
+ * @param publicKeyPem - EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 公钥使用的 NIST 曲线。
+ * @returns 签名与内容、公钥和曲线匹配时返回 `true`。
+ */
+declare function ECDSAVerify(value: string, signature: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<boolean>;
+/**
+ * 生成 ECDH PEM 密钥协商密钥对。
+ *
+ * @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ */
+declare function GenerateECDHKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/**
+ * 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
+ *
+ * @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
+ * @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+ * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 双方密钥使用的 NIST 曲线。
+ * @returns 曲线字段长度的原始 ECDH 共享秘密。
+ */
+declare function DeriveECDHSecret(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
+/**
+ * 使用 ECDH 后以 SHA-256 派生共享密钥。
+ *
+ * @remarks 相比直接使用原始共享秘密，此入口与 .NET `DeriveECDHKeySHA256` 一致并固定输出 32 字节。
+ * @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+ * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 双方密钥使用的 NIST 曲线。
+ * @returns 32 字节共享密钥。
+ */
+declare function DeriveECDHKeySHA256(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
+//#endregion
+export { AESDecrypt, AESDecryptAuthenticated, AESDecryptWithPassword, AESEncrypt, AESEncryptAuthenticated, AESEncryptWithPassword, AesCipherMode, AesPaddingMode, DeriveECDHKeySHA256, DeriveECDHSecret, ECDSASign, ECDSAVerify, EcNamedCurve, FixedTimeEquals, GenerateECDHKeyPair, GenerateECDSAKeyPair, GenerateRSAKeyPair, GenerateRandomBytes, HKDFSHA256, HMACSHA256Encrypt, HMACSHA384Encrypt, HMACSHA512Encrypt, HashPasswordPBKDF2SHA256, MD5Encrypt, PBKDF2SHA256, PemKeyPair, RSADecryptOAEP, RSAEncryptOAEP, RSASignPSS, RSAVerifyPSS, SHA1Encrypt, SHA256Bytes, SHA256Encrypt, SHA384Bytes, SHA384Encrypt, SHA512Bytes, SHA512Encrypt, VerifyPasswordPBKDF2SHA256 };
+//# sourceMappingURL=index.d.mts.map