@fast-china/utils 1.0.38 → 2.0.2

package/dist/crypto/index.mjs

@@ -0,0 +1,843 @@
+import { encodeUtf8, getTextDecoder } from "../internal/text.mjs";
+import { decodeBase64Bytes, decodeBase64UrlBytes, encodeBase64Bytes, encodeBase64UrlBytes } from "../base64/index.mjs";
+import AES from "crypto-js/aes.js";
+import CryptoCore from "crypto-js/core.js";
+import Hex from "crypto-js/enc-hex.js";
+import Utf8 from "crypto-js/enc-utf8.js";
+import MD5 from "crypto-js/md5.js";
+import ECB from "crypto-js/mode-ecb.js";
+import "crypto-js/pad-ansix923.js";
+import Iso10126 from "crypto-js/pad-iso10126.js";
+import NoPadding from "crypto-js/pad-nopadding.js";
+import Pkcs7 from "crypto-js/pad-pkcs7.js";
+import ZeroPadding from "crypto-js/pad-zeropadding.js";
+import SHA1 from "crypto-js/sha1.js";
+//#region src/crypto/index.ts
+/** PBKDF2 默认迭代次数。 */
+const defaultPbkdf2Iterations = 6e5;
+/** PBKDF2 允许的最小迭代次数。 */
+const minimumPbkdf2Iterations = 1e5;
+/** PBKDF2 允许的最大迭代次数，用于限制异常输入造成的计算资源消耗。 */
+const maximumPbkdf2Iterations = 5e6;
+/** 密码允许的最大 UTF-8 字节数。 */
+const maximumPasswordBytes = 1024;
+/** 密码加密接口允许的最大明文字节数。 */
+const maximumPlaintextBytes = 8388608;
+/** 密码解密接口允许的最大协议载荷字符数。 */
+const maximumPayloadLength = 16777216;
+/** 密码加密载荷的协议与算法版本前缀。 */
+const encryptedPayloadPrefix = "FAST-AES-256-GCM-V2";
+/** PBKDF2 密码哈希的协议与算法版本前缀。 */
+const passwordHashPrefix = "FAST-PBKDF2-SHA256-V1";
+/** 直接 AES-GCM 密钥加密载荷的协议版本。 */
+const authenticatedAesPayloadVersion = 1;
+/** 延迟读取的 Web Crypto 全局对象视图，便于在缺少该能力的平台给出明确错误。 */
+const runtimeCryptoGlobals = globalThis;
+/**
+* 获取安全随机数能力。
+*
+* @remarks 随机字节和随机字符串不依赖 SubtleCrypto，因此这里与完整密码原语检查分开。
+* @returns 当前平台的 Crypto 对象。
+* @throws `Error` 当平台缺少 `getRandomValues`。
+*/
+const requireRandomCrypto = () => {
+	const crypto = runtimeCryptoGlobals.crypto;
+	if (typeof crypto?.getRandomValues !== "function") throw new Error("Web Crypto is unavailable in the current runtime.");
+	return crypto;
+};
+/**
+* 获取本模块非随机 API 所需的完整 Web Crypto 能力。
+*
+* @returns 已确认实现摘要、派生、密钥导入导出、加解密、签名和验证方法的 Crypto 对象。
+* @throws `Error` 当任一必要 SubtleCrypto 方法缺失。
+*/
+const requireWebCrypto = () => {
+	const crypto = requireRandomCrypto();
+	const subtle = crypto.subtle;
+	if (typeof subtle?.decrypt !== "function" || typeof subtle.deriveBits !== "function" || typeof subtle.deriveKey !== "function" || typeof subtle.digest !== "function" || typeof subtle.encrypt !== "function" || typeof subtle.exportKey !== "function" || typeof subtle.generateKey !== "function" || typeof subtle.importKey !== "function" || typeof subtle.sign !== "function" || typeof subtle.verify !== "function") throw new Error("Web Crypto SubtleCrypto is unavailable in the current runtime.");
+	return crypto;
+};
+/**
+* 把 Uint8Array 复制为独立的完整 ArrayBuffer。
+*
+* @remarks 不能直接返回 `bytes.buffer`，因为输入可能只是更大 Buffer 的切片。
+* @param bytes - 源字节视图。
+* @returns 长度与视图完全一致、偏移为零的新 ArrayBuffer。
+*/
+const toArrayBuffer = (bytes) => {
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return copy.buffer;
+};
+/** 本模块导出的 PKCS#8 与 SPKI PEM 标签。 */
+const pemLabels = {
+	private: "PRIVATE KEY",
+	public: "PUBLIC KEY"
+};
+/**
+* 把 DER 内容封装为 PEM。
+*
+* @param label - PEM Begin/End 标签，不包含分隔线。
+* @param value - DER 二进制内容。
+* @returns 每行最多 64 个 Base64 字符的 PEM 文本。
+*/
+const toPem = (label, value) => {
+	return `-----BEGIN ${label}-----\n${encodeBase64Bytes(new Uint8Array(value)).match(/.{1,64}/gu)?.join("\n") ?? ""}\n-----END ${label}-----`;
+};
+/**
+* 校验 PEM 标签并还原 DER。
+*
+* @param value - PEM 文本。
+* @param label - 当前算法预期的标签。
+* @returns 独立的 DER ArrayBuffer。
+* @throws `TypeError` 当 Begin/End 标签不匹配或 Base64 内容非法。
+*/
+const fromPem = (value, label) => {
+	const header = `-----BEGIN ${label}-----`;
+	const footer = `-----END ${label}-----`;
+	const trimmed = value.trim();
+	if (!trimmed.startsWith(header) || !trimmed.endsWith(footer)) throw new TypeError(`Expected a ${label} PEM value.`);
+	const encoded = trimmed.slice(header.length, -footer.length).replace(/\s+/gu, "");
+	return toArrayBuffer(decodeBase64Bytes(encoded));
+};
+/**
+* 导出 Web Crypto 密钥对。
+*
+* @param keyPair - 可导出的公私钥对。
+* @returns PKCS#8 私钥和 SPKI 公钥组成的 PEM 对象。
+* @throws `Error` 当平台拒绝导出或密钥格式不兼容。
+*/
+const exportKeyPair = async (keyPair) => {
+	const crypto = requireWebCrypto();
+	const [privateKey, publicKey] = await Promise.all([crypto.subtle.exportKey("pkcs8", keyPair.privateKey), crypto.subtle.exportKey("spki", keyPair.publicKey)]);
+	return {
+		privateKey: toPem(pemLabels.private, privateKey),
+		publicKey: toPem(pemLabels.public, publicKey)
+	};
+};
+/**
+* 缩小 Web Crypto `generateKey` 的联合返回值。
+*
+* @param value - 平台返回的单密钥或密钥对。
+* @returns 同时具有公钥和私钥的密钥对。
+* @throws `Error` 当平台没有按请求生成密钥对。
+*/
+const assertKeyPair = (value) => {
+	if ("privateKey" in value && "publicKey" in value) return value;
+	throw new Error("The runtime did not generate a key pair.");
+};
+/**
+* 校验并编码密码。
+*
+* @param password - 用户提供的密码文本。
+* @returns UTF-8 密码字节。
+* @throws `TypeError` 当密码为空。
+* @throws `RangeError` 当 UTF-8 长度超过 1,024 字节。
+*/
+const encodeValidatedPassword = (password) => {
+	const bytes = encodeUtf8(password);
+	if (bytes.length === 0) throw new TypeError("The encryption password cannot be empty.");
+	if (bytes.length > maximumPasswordBytes) throw new RangeError(`The UTF-8 password cannot exceed ${maximumPasswordBytes} bytes.`);
+	return bytes;
+};
+/**
+* 校验 PBKDF2 迭代次数。
+*
+* @param iterations - 待使用的迭代次数。
+* @returns 校验后的原始整数。
+* @throws `RangeError` 当值不是 100,000 至 5,000,000 的安全整数。
+*/
+const validateIterations = (iterations) => {
+	if (!Number.isSafeInteger(iterations) || iterations < minimumPbkdf2Iterations || iterations > maximumPbkdf2Iterations) throw new RangeError(`iterations must be a safe integer between ${minimumPbkdf2Iterations} and ${maximumPbkdf2Iterations}.`);
+	return iterations;
+};
+/** 把字节格式化为小写十六进制。 */
+const toLowerHex = (value) => Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+/** 把字节格式化为大写十六进制。 */
+const toUpperHex = (value) => toLowerHex(value).toUpperCase();
+/**
+* 使用指定的 Web Crypto HMAC 算法计算原始认证标签。
+*
+* @param value - 要认证的 UTF-8 文本或原始字节。
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+* @param hash - HMAC 使用的 SHA-2 摘要算法。
+* @returns 算法规定长度的原始认证标签。
+* @throws `TypeError` 当密钥为空。
+* @throws `Error` 当运行时缺少所需 Web Crypto 能力。
+*/
+const computeHmacBytes = async (value, key, hash) => {
+	const keyBytes = encodeUtf8(key);
+	if (keyBytes.length === 0) throw new TypeError("The HMAC key cannot be empty.");
+	const crypto = requireWebCrypto();
+	const cryptoKey = await crypto.subtle.importKey("raw", toArrayBuffer(keyBytes), {
+		hash,
+		name: "HMAC"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", cryptoKey, toArrayBuffer(encodeUtf8(value)));
+	return new Uint8Array(signature);
+};
+/**
+* 生成安全随机字节。
+*
+* @param length - 0 至 65,536 的安全整数；上限来自 Web Crypto 单次请求限制。
+* @returns 新建的 `Uint8Array`。
+* @throws 参数非法时抛出 `RangeError`；缺少 Web Crypto 时抛出 `Error`。
+*/
+function GenerateRandomBytes(length) {
+	if (!Number.isSafeInteger(length) || length < 0 || length > 65536) throw new RangeError("length must be a safe integer from 0 through 65,536.");
+	return requireRandomCrypto().getRandomValues(new Uint8Array(length));
+}
+/**
+* 以不提前退出的方式比较两个字节数组。
+*
+* @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
+* 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
+* @param left - 第一字节序列。
+* @param right - 第二字节序列。
+* @returns 长度和每个字节均相同时返回 `true`。
+*/
+function FixedTimeEquals(left, right) {
+	const length = Math.max(left.length, right.length);
+	let difference = left.length === right.length ? 0 : 1;
+	for (let index = 0; index < length; index += 1) difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+	return difference === 0;
+}
+/**
+* 计算 MD5 摘要并返回小写十六进制文本。
+*
+* @remarks MD5 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+* @param value - UTF-8 文本。
+* @returns 32 字符小写十六进制摘要。
+*/
+function MD5Encrypt(value) {
+	return MD5(value).toString(Hex);
+}
+/**
+* 计算 SHA-1 摘要并返回大写十六进制文本。
+*
+* @remarks SHA-1 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+* @param value - UTF-8 文本。
+* @returns 40 字符大写十六进制摘要。
+*/
+function SHA1Encrypt(value) {
+	return SHA1(value).toString(Hex).toUpperCase();
+}
+/**
+* 计算 SHA-256 摘要。
+*
+* @remarks SHA-256 是快速摘要，不适合直接存储或校验密码。
+* @param value - UTF-8 字符串或原始字节。
+* @returns 32 字节摘要。
+* @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+*/
+async function SHA256Bytes(value) {
+	const digest = await requireWebCrypto().subtle.digest("SHA-256", toArrayBuffer(encodeUtf8(value)));
+	return new Uint8Array(digest);
+}
+/**
+* 计算 SHA-256 并格式化为十六进制。
+*
+* @param value - UTF-8 字符串或原始字节。
+* @returns 64 字符大写十六进制文本。
+* @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+*/
+async function SHA256Encrypt(value) {
+	return toUpperHex(await SHA256Bytes(value));
+}
+/**
+* 计算 SHA-384 摘要。
+*
+* @param value - UTF-8 文本或原始字节。
+* @returns 48 字节摘要。
+*/
+async function SHA384Bytes(value) {
+	const digest = await requireWebCrypto().subtle.digest("SHA-384", toArrayBuffer(encodeUtf8(value)));
+	return new Uint8Array(digest);
+}
+/**
+* 计算 SHA-384 并格式化为十六进制文本。
+*
+* @param value - UTF-8 文本或原始字节。
+* @returns 96 个大写十六进制字符组成的摘要。
+*/
+async function SHA384Encrypt(value) {
+	return toUpperHex(await SHA384Bytes(value));
+}
+/**
+* 计算 SHA-512 摘要。
+*
+* @param value - UTF-8 文本或原始字节。
+* @returns 64 字节摘要。
+*/
+async function SHA512Bytes(value) {
+	const digest = await requireWebCrypto().subtle.digest("SHA-512", toArrayBuffer(encodeUtf8(value)));
+	return new Uint8Array(digest);
+}
+/**
+* 计算 SHA-512 并格式化为十六进制文本。
+*
+* @param value - UTF-8 文本或原始字节。
+* @returns 128 个大写十六进制字符组成的摘要。
+*/
+async function SHA512Encrypt(value) {
+	return toUpperHex(await SHA512Bytes(value));
+}
+/**
+* 使用 HMAC-SHA-256 认证文本，并返回十六进制标签。
+*
+* @param value - 要认证的 UTF-8 文本或原始字节。
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+* @returns 64 个小写十六进制字符组成的认证标签。
+*/
+async function HMACSHA256Encrypt(value, key) {
+	return toLowerHex(await computeHmacBytes(value, key, "SHA-256"));
+}
+/**
+* 使用 HMAC-SHA-384 认证文本或字节，并返回十六进制标签。
+*
+* @param value - 要认证的 UTF-8 文本或原始字节。
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+* @returns 96 个小写十六进制字符组成的认证标签。
+*/
+async function HMACSHA384Encrypt(value, key) {
+	return toLowerHex(await computeHmacBytes(value, key, "SHA-384"));
+}
+/**
+* 使用 HMAC-SHA-512 认证文本或字节，并返回十六进制标签。
+*
+* @param value - 要认证的 UTF-8 文本或原始字节。
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+* @returns 128 个小写十六进制字符组成的认证标签。
+*/
+async function HMACSHA512Encrypt(value, key) {
+	return toLowerHex(await computeHmacBytes(value, key, "SHA-512"));
+}
+/**
+* 使用 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`。
+*/
+async function PBKDF2SHA256(password, salt, iterations = defaultPbkdf2Iterations, outputLength = 32) {
+	const passwordBytes = encodeValidatedPassword(password);
+	if (salt.length < 8) throw new RangeError("The PBKDF2 salt must contain at least 8 bytes; 16 or more is recommended.");
+	if (!Number.isSafeInteger(outputLength) || outputLength < 1 || outputLength > 1024) throw new RangeError("outputLength must be a safe integer between 1 and 1,024.");
+	const crypto = requireWebCrypto();
+	const material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveBits"]);
+	const derived = await crypto.subtle.deriveBits({
+		hash: "SHA-256",
+		iterations: validateIterations(iterations),
+		name: "PBKDF2",
+		salt: toArrayBuffer(salt)
+	}, material, outputLength * 8);
+	return new Uint8Array(derived);
+}
+/**
+* 生成可持久化的随机盐 PBKDF2-HMAC-SHA-256 密码哈希。
+*
+* @param password - 1 至 1,024 UTF-8 字节的密码。
+* @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
+* @returns 包含版本、迭代次数、16 字节随机盐和 32 字节派生密钥的自描述字符串。
+*/
+async function HashPasswordPBKDF2SHA256(password, iterations = defaultPbkdf2Iterations) {
+	const salt = GenerateRandomBytes(16);
+	const derivedKey = await PBKDF2SHA256(password, salt, iterations);
+	return [
+		passwordHashPrefix,
+		String(iterations),
+		encodeBase64UrlBytes(salt),
+		encodeBase64UrlBytes(derivedKey)
+	].join(":");
+}
+/**
+* 验证 {@link HashPasswordPBKDF2SHA256} 生成的密码哈希。
+*
+* @param password - 要验证的密码。
+* @param passwordHash - 自描述的 PBKDF2-HMAC-SHA-256 密码哈希。
+* @returns 格式有效且密码匹配时返回 `true`；格式无效或密码错误时返回 `false`。
+*/
+async function VerifyPasswordPBKDF2SHA256(password, passwordHash) {
+	try {
+		const parts = passwordHash.split(":");
+		if (parts.length !== 4 || parts[0] !== passwordHashPrefix) return false;
+		const iterations = validateIterations(Number(parts[1]));
+		const salt = decodeBase64UrlBytes(parts[2] ?? "");
+		const expected = decodeBase64UrlBytes(parts[3] ?? "");
+		if (salt.length !== 16 || expected.length !== 32) return false;
+		return FixedTimeEquals(await PBKDF2SHA256(password, salt, iterations, expected.length), expected);
+	} catch {
+		return false;
+	}
+}
+/**
+* 使用 RFC 5869 HKDF-SHA-256 派生上下文隔离的密钥材料。
+*
+* @param inputKeyMaterial - 输入密钥材料，例如 ECDH 原始共享秘密。
+* @param salt - 可选盐；空值按 RFC 5869 的零盐语义处理。
+* @param info - 应用、协议和密钥用途上下文。
+* @param outputLength - 输出长度，范围为 1 至 8,160 字节。
+* @returns 与 `salt` 和 `info` 绑定的派生密钥。
+*/
+async function HKDFSHA256(inputKeyMaterial, salt = /* @__PURE__ */ new Uint8Array(), info = /* @__PURE__ */ new Uint8Array(), outputLength = 32) {
+	if (!Number.isSafeInteger(outputLength) || outputLength < 1 || outputLength > 8160) throw new RangeError("outputLength must be a safe integer between 1 and 8,160.");
+	const crypto = requireWebCrypto();
+	const material = await crypto.subtle.importKey("raw", toArrayBuffer(inputKeyMaterial), "HKDF", false, ["deriveBits"]);
+	const derived = await crypto.subtle.deriveBits({
+		hash: "SHA-256",
+		info: toArrayBuffer(info),
+		name: "HKDF",
+		salt: toArrayBuffer(salt)
+	}, material, outputLength * 8);
+	return new Uint8Array(derived);
+}
+/**
+* 使用 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`。
+*/
+function AESEncrypt(dataStr, key, vector, cipherMode = "CBC", paddingMode = "PKCS7") {
+	if (dataStr.trim().length === 0 || key.trim().length === 0 || vector.trim().length === 0) return null;
+	if (cipherMode !== "CBC" && cipherMode !== "ECB") throw new RangeError("cipherMode must be \"CBC\" or \"ECB\".");
+	let padding = Pkcs7;
+	switch (paddingMode) {
+		case "None":
+			padding = NoPadding;
+			break;
+		case "PKCS7": break;
+		case "Zeros":
+			padding = ZeroPadding;
+			break;
+		case "ANSIX923":
+			padding = CryptoCore.pad.AnsiX923;
+			break;
+		case "ISO10126":
+			padding = Iso10126;
+			break;
+		default: throw new RangeError("paddingMode is not supported.");
+	}
+	if (paddingMode === "None" && encodeUtf8(dataStr).length % 16 !== 0) throw new RangeError("AES plaintext must contain a whole number of 16-byte blocks when paddingMode is None.");
+	const keyBytes = Utf8.parse(key.padEnd(32, "f").slice(0, 32));
+	const vectorBytes = Utf8.parse(vector.padEnd(16, "f").slice(0, 16));
+	return AES.encrypt(dataStr, keyBytes, cipherMode === "CBC" ? {
+		iv: vectorBytes,
+		padding
+	} : {
+		iv: vectorBytes,
+		mode: ECB,
+		padding
+	}).toString();
+}
+/**
+* 使用 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、密钥或密文无效时抛出错误。
+*/
+function AESDecrypt(dataStr, key, vector, cipherMode = "CBC", paddingMode = "PKCS7") {
+	if (dataStr.trim().length === 0 || key.trim().length === 0 || vector.trim().length === 0) return null;
+	if (cipherMode !== "CBC" && cipherMode !== "ECB") throw new RangeError("cipherMode must be \"CBC\" or \"ECB\".");
+	let padding = Pkcs7;
+	switch (paddingMode) {
+		case "None":
+			padding = NoPadding;
+			break;
+		case "PKCS7": break;
+		case "Zeros":
+			padding = NoPadding;
+			break;
+		case "ANSIX923":
+			padding = CryptoCore.pad.AnsiX923;
+			break;
+		case "ISO10126":
+			padding = Iso10126;
+			break;
+		default: throw new RangeError("paddingMode is not supported.");
+	}
+	const ciphertextBytes = decodeBase64Bytes(dataStr);
+	if (ciphertextBytes.length === 0 || ciphertextBytes.length % 16 !== 0) throw new RangeError("AES ciphertext must contain one or more complete 16-byte blocks.");
+	const keyBytes = Utf8.parse(key.padEnd(32, "f").slice(0, 32));
+	const vectorBytes = Utf8.parse(vector.padEnd(16, "f").slice(0, 16));
+	return AES.decrypt(dataStr, keyBytes, cipherMode === "CBC" ? {
+		iv: vectorBytes,
+		padding
+	} : {
+		iv: vectorBytes,
+		mode: ECB,
+		padding
+	}).toString(Utf8);
+}
+/**
+* 使用 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 时抛出错误。
+*/
+async function AESEncryptAuthenticated(plaintext, key) {
+	if (key.trim().length === 0) throw new TypeError("The encryption key cannot be empty.");
+	const crypto = requireWebCrypto();
+	const keyBytes = await SHA256Bytes(key);
+	const cryptoKey = await crypto.subtle.importKey("raw", toArrayBuffer(keyBytes), { name: "AES-GCM" }, false, ["encrypt"]);
+	const nonce = GenerateRandomBytes(12);
+	const encrypted = new Uint8Array(await crypto.subtle.encrypt({
+		iv: toArrayBuffer(nonce),
+		name: "AES-GCM",
+		tagLength: 128
+	}, cryptoKey, toArrayBuffer(encodeUtf8(plaintext))));
+	const ciphertextLength = encrypted.length - 16;
+	const payload = new Uint8Array(1 + nonce.length + 16 + ciphertextLength);
+	payload[0] = authenticatedAesPayloadVersion;
+	payload.set(nonce, 1);
+	payload.set(encrypted.subarray(ciphertextLength), 1 + nonce.length);
+	payload.set(encrypted.subarray(0, ciphertextLength), 1 + nonce.length + 16);
+	return encodeBase64Bytes(payload);
+}
+/**
+* 解密并认证 .NET `AESEncryptAuthenticated` 或 {@link AESEncryptAuthenticated} 生成的载荷。
+*
+* @param payload - Base64 编码的 v1 AES-GCM 二进制载荷。
+* @param key - 加密时使用的非空 UTF-8 文本密钥。
+* @returns 通过认证的 UTF-8 明文。
+* @throws 载荷格式无效、密钥错误或认证失败时抛出错误。
+*/
+async function AESDecryptAuthenticated(payload, key) {
+	if (key.trim().length === 0) throw new TypeError("The encryption key cannot be empty.");
+	const decoded = decodeBase64Bytes(payload);
+	if (decoded.length < 29 || decoded[0] !== authenticatedAesPayloadVersion) throw new TypeError("The AES-GCM payload format or version is not supported.");
+	const nonce = decoded.subarray(1, 13);
+	const tag = decoded.subarray(13, 29);
+	const ciphertext = decoded.subarray(29);
+	const ciphertextAndTag = new Uint8Array(ciphertext.length + tag.length);
+	ciphertextAndTag.set(ciphertext);
+	ciphertextAndTag.set(tag, ciphertext.length);
+	const crypto = requireWebCrypto();
+	const keyBytes = await SHA256Bytes(key);
+	const cryptoKey = await crypto.subtle.importKey("raw", toArrayBuffer(keyBytes), { name: "AES-GCM" }, false, ["decrypt"]);
+	const plaintext = await crypto.subtle.decrypt({
+		iv: toArrayBuffer(nonce),
+		name: "AES-GCM",
+		tagLength: 128
+	}, cryptoKey, toArrayBuffer(ciphertextAndTag));
+	return getTextDecoder().decode(plaintext);
+}
+/**
+* 使用 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`。
+*/
+async function AESEncryptWithPassword(plaintext, password, iterations = defaultPbkdf2Iterations) {
+	const passwordBytes = encodeValidatedPassword(password);
+	const plaintextBytes = encodeUtf8(plaintext);
+	if (plaintextBytes.length > maximumPlaintextBytes) throw new RangeError(`The UTF-8 plaintext cannot exceed ${maximumPlaintextBytes} bytes.`);
+	const validatedIterations = validateIterations(iterations);
+	const crypto = requireWebCrypto();
+	const salt = GenerateRandomBytes(16);
+	const iv = GenerateRandomBytes(12);
+	const material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveKey"]);
+	const key = await crypto.subtle.deriveKey({
+		hash: "SHA-256",
+		iterations: validatedIterations,
+		name: "PBKDF2",
+		salt: toArrayBuffer(salt)
+	}, material, {
+		length: 256,
+		name: "AES-GCM"
+	}, false, ["encrypt"]);
+	const ciphertext = await crypto.subtle.encrypt({
+		additionalData: toArrayBuffer(encodeUtf8(encryptedPayloadPrefix)),
+		iv: toArrayBuffer(iv),
+		name: "AES-GCM",
+		tagLength: 128
+	}, key, plaintextBytes);
+	return [
+		encryptedPayloadPrefix,
+		String(validatedIterations),
+		encodeBase64UrlBytes(salt),
+		encodeBase64UrlBytes(iv),
+		encodeBase64UrlBytes(new Uint8Array(ciphertext))
+	].join(":");
+}
+/**
+* 解密 {@link AESEncryptWithPassword} 生成的 v2 认证载荷。
+*
+* @param payload - 未修改的 v2 载荷，最大约 16 MiB 文本。
+* @param password - 加密时使用的口令。
+* @returns 原始 UTF-8 文本。
+* @throws 格式或字段非法时抛出 `TypeError`，载荷过大时抛出 `RangeError`，认证或密码
+* 失败及缺少平台能力时抛出 `Error`。
+*/
+async function AESDecryptWithPassword(payload, password) {
+	const passwordBytes = encodeValidatedPassword(password);
+	if (payload.length > maximumPayloadLength) throw new RangeError("The encrypted payload exceeds the supported size.");
+	const parts = payload.split(":");
+	if (parts.length !== 5 || parts[0] !== encryptedPayloadPrefix) throw new TypeError("The encrypted payload format is not supported.");
+	let iterations;
+	let salt;
+	let iv;
+	let ciphertext;
+	try {
+		iterations = validateIterations(Number(parts[1]));
+		salt = decodeBase64UrlBytes(parts[2] ?? "");
+		iv = decodeBase64UrlBytes(parts[3] ?? "");
+		ciphertext = decodeBase64UrlBytes(parts[4] ?? "");
+		if (salt.length !== 16 || iv.length !== 12 || ciphertext.length < 16) throw new TypeError("The encrypted payload has invalid field lengths.");
+	} catch (cause) {
+		throw new TypeError("The encrypted payload contains invalid fields.", { cause });
+	}
+	const crypto = requireWebCrypto();
+	const textDecoder = getTextDecoder();
+	try {
+		const material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveKey"]);
+		const key = await crypto.subtle.deriveKey({
+			hash: "SHA-256",
+			iterations,
+			name: "PBKDF2",
+			salt: toArrayBuffer(salt)
+		}, material, {
+			length: 256,
+			name: "AES-GCM"
+		}, false, ["decrypt"]);
+		const plaintext = await crypto.subtle.decrypt({
+			additionalData: toArrayBuffer(encodeUtf8(encryptedPayloadPrefix)),
+			iv: toArrayBuffer(iv),
+			name: "AES-GCM",
+			tagLength: 128
+		}, key, toArrayBuffer(ciphertext));
+		return textDecoder.decode(plaintext);
+	} catch (cause) {
+		throw new Error("The payload could not be authenticated or decrypted.", { cause });
+	}
+}
+/**
+* 生成可供 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`。
+*/
+async function GenerateRSAKeyPair(modulusLength = 2048) {
+	if (!Number.isSafeInteger(modulusLength) || modulusLength < 2048 || modulusLength % 256 !== 0) throw new RangeError("modulusLength must be a safe integer of at least 2048 and divisible by 256.");
+	const crypto = requireWebCrypto();
+	const keyPair = assertKeyPair(await crypto.subtle.generateKey({
+		hash: "SHA-256",
+		modulusLength,
+		name: "RSA-OAEP",
+		publicExponent: Uint8Array.of(1, 0, 1)
+	}, true, ["decrypt", "encrypt"]));
+	return exportKeyPair(keyPair);
+}
+/**
+* 使用 RSA-OAEP/SHA-256 公钥加密 UTF-8 文本。
+*
+* @param plaintext - 要加密的 UTF-8 文本；长度必须满足 RSA-OAEP 模数限制。
+* @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+* @returns Base64 编码的 RSA 密文。
+* @throws 公钥格式无效或明文超过 RSA-OAEP 容量时抛出错误。
+*/
+async function RSAEncryptOAEP(plaintext, publicKeyPem) {
+	const crypto = requireWebCrypto();
+	const key = await crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
+		hash: "SHA-256",
+		name: "RSA-OAEP"
+	}, false, ["encrypt"]);
+	const ciphertext = await crypto.subtle.encrypt({ name: "RSA-OAEP" }, key, toArrayBuffer(encodeUtf8(plaintext)));
+	return encodeBase64Bytes(new Uint8Array(ciphertext));
+}
+/**
+* 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。
+*
+* @param ciphertext - Base64 编码的 RSA 密文。
+* @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+* @returns 解密后的 UTF-8 文本。
+* @throws 私钥、Base64 或密文无效时抛出错误。
+*/
+async function RSADecryptOAEP(ciphertext, privateKeyPem) {
+	const crypto = requireWebCrypto();
+	const key = await crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
+		hash: "SHA-256",
+		name: "RSA-OAEP"
+	}, false, ["decrypt"]);
+	const plaintext = await crypto.subtle.decrypt({ name: "RSA-OAEP" }, key, toArrayBuffer(decodeBase64Bytes(ciphertext)));
+	return getTextDecoder().decode(plaintext);
+}
+/**
+* 使用 RSA-PSS/SHA-256 私钥签名文本或字节。
+*
+* @param value - 要签名的 UTF-8 文本或原始字节。
+* @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+* @returns Base64 编码的 RSA-PSS 签名；盐长度固定为 32 字节。
+* @throws 私钥格式无效或签名失败时抛出错误。
+*/
+async function RSASignPSS(value, privateKeyPem) {
+	const crypto = requireWebCrypto();
+	const key = await crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
+		hash: "SHA-256",
+		name: "RSA-PSS"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign({
+		name: "RSA-PSS",
+		saltLength: 32
+	}, key, toArrayBuffer(encodeUtf8(value)));
+	return encodeBase64Bytes(new Uint8Array(signature));
+}
+/**
+* 使用 RSA-PSS/SHA-256 公钥验证 Base64 签名。
+*
+* @param value - 签名时使用的 UTF-8 文本或原始字节。
+* @param signature - Base64 编码的 RSA-PSS 签名。
+* @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+* @returns 签名与内容、公钥匹配时返回 `true`。
+* @throws 公钥或 Base64 格式无效时抛出错误。
+*/
+async function RSAVerifyPSS(value, signature, publicKeyPem) {
+	const crypto = requireWebCrypto();
+	const key = await crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
+		hash: "SHA-256",
+		name: "RSA-PSS"
+	}, false, ["verify"]);
+	return crypto.subtle.verify({
+		name: "RSA-PSS",
+		saltLength: 32
+	}, key, toArrayBuffer(decodeBase64Bytes(signature)), toArrayBuffer(encodeUtf8(value)));
+}
+/**
+* 生成 ECDSA PEM 签名密钥对。
+*
+* @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+* @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+*/
+async function GenerateECDSAKeyPair(namedCurve = "P-256") {
+	const crypto = requireWebCrypto();
+	const keyPair = assertKeyPair(await crypto.subtle.generateKey({
+		name: "ECDSA",
+		namedCurve
+	}, true, ["sign", "verify"]));
+	return exportKeyPair(keyPair);
+}
+/**
+* 使用 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 签名。
+*/
+async function ECDSASign(value, privateKeyPem, namedCurve = "P-256") {
+	const crypto = requireWebCrypto();
+	const key = await crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
+		name: "ECDSA",
+		namedCurve
+	}, false, ["sign"]);
+	const hash = namedCurve === "P-256" ? "SHA-256" : namedCurve === "P-384" ? "SHA-384" : "SHA-512";
+	const signature = await crypto.subtle.sign({
+		hash,
+		name: "ECDSA"
+	}, key, toArrayBuffer(encodeUtf8(value)));
+	return encodeBase64Bytes(new Uint8Array(signature));
+}
+/**
+* 使用 ECDSA 公钥验证 Base64 签名。
+*
+* @param value - 签名时使用的 UTF-8 文本或原始字节。
+* @param signature - Base64 编码的 IEEE P1363 ECDSA 签名。
+* @param publicKeyPem - EC SubjectPublicKeyInfo PEM 公钥。
+* @param namedCurve - 公钥使用的 NIST 曲线。
+* @returns 签名与内容、公钥和曲线匹配时返回 `true`。
+*/
+async function ECDSAVerify(value, signature, publicKeyPem, namedCurve = "P-256") {
+	const crypto = requireWebCrypto();
+	const key = await crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
+		name: "ECDSA",
+		namedCurve
+	}, false, ["verify"]);
+	const hash = namedCurve === "P-256" ? "SHA-256" : namedCurve === "P-384" ? "SHA-384" : "SHA-512";
+	return crypto.subtle.verify({
+		hash,
+		name: "ECDSA"
+	}, key, toArrayBuffer(decodeBase64Bytes(signature)), toArrayBuffer(encodeUtf8(value)));
+}
+/**
+* 生成 ECDH PEM 密钥协商密钥对。
+*
+* @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+* @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+*/
+async function GenerateECDHKeyPair(namedCurve = "P-256") {
+	const crypto = requireWebCrypto();
+	const keyPair = assertKeyPair(await crypto.subtle.generateKey({
+		name: "ECDH",
+		namedCurve
+	}, true, ["deriveBits"]));
+	return exportKeyPair(keyPair);
+}
+/**
+* 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
+*
+* @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
+* @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+* @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+* @param namedCurve - 双方密钥使用的 NIST 曲线。
+* @returns 曲线字段长度的原始 ECDH 共享秘密。
+*/
+async function DeriveECDHSecret(privateKeyPem, publicKeyPem, namedCurve = "P-256") {
+	const crypto = requireWebCrypto();
+	const [privateKey, publicKey] = await Promise.all([crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
+		name: "ECDH",
+		namedCurve
+	}, false, ["deriveBits"]), crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
+		name: "ECDH",
+		namedCurve
+	}, false, [])]);
+	const bitLength = namedCurve === "P-256" ? 256 : namedCurve === "P-384" ? 384 : 528;
+	const secret = await crypto.subtle.deriveBits({
+		name: "ECDH",
+		public: publicKey
+	}, privateKey, bitLength);
+	return new Uint8Array(secret);
+}
+/**
+* 使用 ECDH 后以 SHA-256 派生共享密钥。
+*
+* @remarks 相比直接使用原始共享秘密，此入口与 .NET `DeriveECDHKeySHA256` 一致并固定输出 32 字节。
+* @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+* @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+* @param namedCurve - 双方密钥使用的 NIST 曲线。
+* @returns 32 字节共享密钥。
+*/
+async function DeriveECDHKeySHA256(privateKeyPem, publicKeyPem, namedCurve = "P-256") {
+	const secret = await DeriveECDHSecret(privateKeyPem, publicKeyPem, namedCurve);
+	const digest = await requireWebCrypto().subtle.digest("SHA-256", toArrayBuffer(secret));
+	return new Uint8Array(digest);
+}
+//#endregion
+export { AESDecrypt, AESDecryptAuthenticated, AESDecryptWithPassword, AESEncrypt, AESEncryptAuthenticated, AESEncryptWithPassword, DeriveECDHKeySHA256, DeriveECDHSecret, ECDSASign, ECDSAVerify, FixedTimeEquals, GenerateECDHKeyPair, GenerateECDSAKeyPair, GenerateRSAKeyPair, GenerateRandomBytes, HKDFSHA256, HMACSHA256Encrypt, HMACSHA384Encrypt, HMACSHA512Encrypt, HashPasswordPBKDF2SHA256, MD5Encrypt, PBKDF2SHA256, RSADecryptOAEP, RSAEncryptOAEP, RSASignPSS, RSAVerifyPSS, SHA1Encrypt, SHA256Bytes, SHA256Encrypt, SHA384Bytes, SHA384Encrypt, SHA512Bytes, SHA512Encrypt, VerifyPasswordPBKDF2SHA256 };
+
+//# sourceMappingURL=index.mjs.map