@fast-china/utils 2.1.9 → 2.1.11

package/dist/crypto/index.mjs

@@ -1,5 +1,4 @@
-import { createDecodedText, encodeUtf8, getTextDecoder } from "../internal/text.mjs";
-import { runtimeGlobals } from "../internal/runtime.mjs";
+import { createDecodedText, decodeUtf8, encodeUtf8 } from "../internal/text.mjs";
 import { decodeBase64Bytes, decodeBase64UrlBytes, encodeBase64Bytes, encodeBase64UrlBytes } from "../base64/index.mjs";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
@@ -2241,26 +2240,23 @@ const passwordHashPrefix = "FAST-PBKDF2-SHA256-V1";
 const authenticatedAesPayloadVersion = 1;
 /** 校验 JavaScript 调用方传入的 AES 分组模式。 */
 const assertAesCipherMode = (value) => {
-	if (value !== "CBC" && value !== "ECB") throw new RangeError("`cipherMode` 必须是 `CBC` 或 `ECB`。");
+	if (value !== "CBC" && value !== "ECB") throw new RangeError("`cipherMode` must be `CBC` or `ECB`.");
 };
 /**
-* 获取本模块非随机 API 所需的完整 Web Crypto 能力。
+* 检查当前操作所需的 Web Crypto 能力。
 *
-* @returns 已确认实现摘要、派生、密钥导入导出、加解密、签名和验证方法的 Crypto 对象。
-* @throws `Error` 当任一必要 SubtleCrypto 方法缺失。
+* @param methods - 当前操作需要的 SubtleCrypto 方法
+* @throws `Error` 当当前操作需要的 SubtleCrypto 方法缺失。
 */
-const requireWebCrypto = () => {
-	const crypto = runtimeGlobals.crypto;
-	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。");
-	return crypto;
+const assertWebCrypto = (...methods) => {
+	if (typeof crypto === "undefined" || methods.some((method) => typeof crypto.subtle?.[method] !== "function")) throw new Error("The current runtime does not support Web Crypto SubtleCrypto.");
 };
 /**
 * 把 Uint8Array 复制为独立的完整 ArrayBuffer。
 *
 * @remarks 不能直接返回 `bytes.buffer`，因为输入可能只是更大 Buffer 的切片。
-* @param bytes - 源字节视图。
-* @returns 长度与视图完全一致、偏移为零的新 ArrayBuffer。
+* @param bytes - 源字节视图
+* @returns 长度与视图完全一致、偏移为零的新 ArrayBuffer
 */
 const toArrayBuffer = (bytes) => {
 	const copy = new Uint8Array(bytes.byteLength);
@@ -2276,8 +2272,8 @@ const pemLabels = {
 * 把 DER 内容封装为 PEM。
 *
 * @param label - PEM Begin/End 标签，不包含分隔线。
-* @param value - DER 二进制内容。
-* @returns 每行最多 64 个 Base64 字符的 PEM 文本。
+* @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}-----`;
@@ -2285,28 +2281,28 @@ const toPem = (label, value) => {
 /**
 * 校验 PEM 标签并还原 DER。
 *
-* @param value - PEM 文本。
-* @param label - 当前算法预期的标签。
-* @returns 独立的 DER ArrayBuffer。
+* @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(`应提供 ${label} 格式的 PEM 值。`);
+	if (!trimmed.startsWith(header) || !trimmed.endsWith(footer)) throw new TypeError(`Expected a PEM value with the ${label} label.`);
 	const encoded = trimmed.slice(header.length, -footer.length).replace(/\s+/gu, "");
 	return toArrayBuffer(decodeBase64Bytes(encoded));
 };
 /**
 * 导出 Web Crypto 密钥对。
 *
-* @param keyPair - 可导出的公私钥对。
-* @returns PKCS#8 私钥和 SPKI 公钥组成的 PEM 对象。
+* @param keyPair - 可导出的公私钥对
+* @returns PKCS#8 私钥和 SPKI 公钥组成的 PEM 对象
 * @throws `Error` 当平台拒绝导出或密钥格式不兼容。
 */
 const exportKeyPair = async (keyPair) => {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("exportKey");
 	const [privateKey, publicKey] = await Promise.all([crypto.subtle.exportKey("pkcs8", keyPair.privateKey), crypto.subtle.exportKey("spki", keyPair.publicKey)]);
 	return {
 		privateKey: toPem(pemLabels.private, privateKey),
@@ -2316,37 +2312,37 @@ const exportKeyPair = async (keyPair) => {
 /**
 * 缩小 Web Crypto `generateKey` 的联合返回值。
 *
-* @param value - 平台返回的单密钥或密钥对。
-* @returns 同时具有公钥和私钥的密钥对。
+* @param value - 平台返回的单密钥或密钥对
+* @returns 同时具有公钥和私钥的密钥对
 * @throws `Error` 当平台没有按请求生成密钥对。
 */
 const assertKeyPair = (value) => {
 	if ("privateKey" in value && "publicKey" in value) return value;
-	throw new Error("当前运行环境未生成密钥对。");
+	throw new Error("The current runtime did not generate a key pair.");
 };
 /**
 * 校验并编码密码。
 *
-* @param password - 用户提供的密码文本。
-* @returns UTF-8 密码字节。
+* @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("加密密码不能为空。");
-	if (bytes.length > maximumPasswordBytes) throw new RangeError(`UTF-8 密码不能超过 ${maximumPasswordBytes} 字节。`);
+	if (bytes.length === 0) throw new TypeError("The encryption password must not be empty.");
+	if (bytes.length > maximumPasswordBytes) throw new RangeError(`The UTF-8 password must not exceed ${maximumPasswordBytes} bytes.`);
 	return bytes;
 };
 /**
 * 校验 PBKDF2 迭代次数。
 *
-* @param iterations - 待使用的迭代次数。
-* @returns 校验后的原始整数。
+* @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\` 必须是 ${minimumPbkdf2Iterations} 到 ${maximumPbkdf2Iterations} 之间的安全整数。`);
+	if (!Number.isSafeInteger(iterations) || iterations < minimumPbkdf2Iterations || iterations > maximumPbkdf2Iterations) throw new RangeError(`\`iterations\` must be a safe integer between ${minimumPbkdf2Iterations} and ${maximumPbkdf2Iterations}.`);
 	return iterations;
 };
 /** 把字节格式化为小写十六进制。 */
@@ -2356,17 +2352,17 @@ const toUpperHex = (value) => toLowerHex(value).toUpperCase();
 /**
 * 使用指定的 Web Crypto HMAC 算法计算原始认证标签。
 *
-* @param value - 要认证的 UTF-8 文本或原始字节。
-* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
-* @param hash - HMAC 使用的 SHA-2 摘要算法。
-* @returns 算法规定长度的原始认证标签。
+* @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("HMAC 密钥不能为空。");
-	const crypto = requireWebCrypto();
+	if (keyBytes.length === 0) throw new TypeError("The HMAC key must not be empty.");
+	assertWebCrypto("importKey", "sign");
 	const cryptoKey = await crypto.subtle.importKey("raw", toArrayBuffer(keyBytes), {
 		hash,
 		name: "HMAC"
@@ -2378,15 +2374,14 @@ const computeHmacBytes = async (value, key, hash) => {
 * 生成随机字节。
 *
 * @remarks 优先使用 Web Crypto；平台缺少安全随机能力时回退到 `Math.random()`。
-* @param length - 0 至 65,536 的安全整数。
-* @returns 新建的 `Uint8Array`。
+* @param length - 0 至 65,536 的安全整数
+* @returns 新建的 `Uint8Array`
 * @throws 参数非法时抛出 `RangeError`。
 */
 function GenerateRandomBytes(length) {
-	if (!Number.isSafeInteger(length) || length < 0 || length > 65536) throw new RangeError("`length` 必须是 0 到 65,536 之间的安全整数。");
+	if (!Number.isSafeInteger(length) || length < 0 || length > 65536) throw new RangeError("`length` must be a safe integer between 0 and 65,536.");
 	const bytes = new Uint8Array(length);
-	const crypto = runtimeGlobals.crypto;
-	if (typeof crypto?.getRandomValues === "function") return crypto.getRandomValues(bytes);
+	if (typeof crypto !== "undefined" && typeof crypto?.getRandomValues === "function") return crypto.getRandomValues(bytes);
 	for (let index = 0; index < bytes.length; index += 1) bytes[index] = Math.floor(Math.random() * 256);
 	return bytes;
 }
@@ -2395,8 +2390,8 @@ function GenerateRandomBytes(length) {
 *
 * @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
 * 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
-* @param left - 第一字节序列。
-* @param right - 第二字节序列。
+* @param left - 第一字节序列
+* @param right - 第二字节序列
 * @returns 长度和每个字节均相同时返回 `true`。
 */
 function FixedTimeEquals(left, right) {
@@ -2409,8 +2404,8 @@ function FixedTimeEquals(left, right) {
 * 计算 MD5 摘要并返回小写十六进制文本。
 *
 * @remarks MD5 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
-* @param value - UTF-8 文本。
-* @returns 32 字符小写十六进制摘要。
+* @param value - UTF-8 文本
+* @returns 32 字符小写十六进制摘要
 */
 function MD5Encrypt(value) {
 	return (0, import_md5.default)(value).toString(import_enc_hex.default);
@@ -2419,8 +2414,8 @@ function MD5Encrypt(value) {
 * 计算 SHA-1 摘要并返回大写十六进制文本。
 *
 * @remarks SHA-1 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
-* @param value - UTF-8 文本。
-* @returns 40 字符大写十六进制摘要。
+* @param value - UTF-8 文本
+* @returns 40 字符大写十六进制摘要
 */
 function SHA1Encrypt(value) {
 	return (0, import_sha1.default)(value).toString(import_enc_hex.default).toUpperCase();
@@ -2429,20 +2424,21 @@ function SHA1Encrypt(value) {
 * 计算 SHA-256 摘要。
 *
 * @remarks SHA-256 是快速摘要，不适合直接存储或校验密码。
-* @param value - UTF-8 字符串或原始字节。
-* @returns 32 字节摘要。
-* @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+* @param value - UTF-8 字符串或原始字节
+* @returns 32 字节摘要
+* @throws 缺少 Web Crypto 时抛出 `Error`。
 */
 async function SHA256Bytes(value) {
-	const digest = await requireWebCrypto().subtle.digest("SHA-256", toArrayBuffer(encodeUtf8(value)));
+	assertWebCrypto("digest");
+	const digest = await crypto.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`。
+* @param value - UTF-8 字符串或原始字节
+* @returns 64 字符大写十六进制文本
+* @throws 缺少 Web Crypto 时抛出 `Error`。
 */
 async function SHA256Encrypt(value) {
 	return toUpperHex(await SHA256Bytes(value));
@@ -2450,18 +2446,19 @@ async function SHA256Encrypt(value) {
 /**
 * 计算 SHA-384 摘要。
 *
-* @param value - UTF-8 文本或原始字节。
-* @returns 48 字节摘要。
+* @param value - UTF-8 文本或原始字节
+* @returns 48 字节摘要
 */
 async function SHA384Bytes(value) {
-	const digest = await requireWebCrypto().subtle.digest("SHA-384", toArrayBuffer(encodeUtf8(value)));
+	assertWebCrypto("digest");
+	const digest = await crypto.subtle.digest("SHA-384", toArrayBuffer(encodeUtf8(value)));
 	return new Uint8Array(digest);
 }
 /**
 * 计算 SHA-384 并格式化为十六进制文本。
 *
-* @param value - UTF-8 文本或原始字节。
-* @returns 96 个大写十六进制字符组成的摘要。
+* @param value - UTF-8 文本或原始字节
+* @returns 96 个大写十六进制字符组成的摘要
 */
 async function SHA384Encrypt(value) {
 	return toUpperHex(await SHA384Bytes(value));
@@ -2469,18 +2466,19 @@ async function SHA384Encrypt(value) {
 /**
 * 计算 SHA-512 摘要。
 *
-* @param value - UTF-8 文本或原始字节。
-* @returns 64 字节摘要。
+* @param value - UTF-8 文本或原始字节
+* @returns 64 字节摘要
 */
 async function SHA512Bytes(value) {
-	const digest = await requireWebCrypto().subtle.digest("SHA-512", toArrayBuffer(encodeUtf8(value)));
+	assertWebCrypto("digest");
+	const digest = await crypto.subtle.digest("SHA-512", toArrayBuffer(encodeUtf8(value)));
 	return new Uint8Array(digest);
 }
 /**
 * 计算 SHA-512 并格式化为十六进制文本。
 *
-* @param value - UTF-8 文本或原始字节。
-* @returns 128 个大写十六进制字符组成的摘要。
+* @param value - UTF-8 文本或原始字节
+* @returns 128 个大写十六进制字符组成的摘要
 */
 async function SHA512Encrypt(value) {
 	return toUpperHex(await SHA512Bytes(value));
@@ -2488,9 +2486,9 @@ async function SHA512Encrypt(value) {
 /**
 * 使用 HMAC-SHA-256 认证文本，并返回十六进制标签。
 *
-* @param value - 要认证的 UTF-8 文本或原始字节。
-* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
-* @returns 64 个小写十六进制字符组成的认证标签。
+* @param value - 要认证的 UTF-8 文本或原始字节
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节
+* @returns 64 个小写十六进制字符组成的认证标签
 */
 async function HMACSHA256Encrypt(value, key) {
 	return toLowerHex(await computeHmacBytes(value, key, "SHA-256"));
@@ -2498,9 +2496,9 @@ async function HMACSHA256Encrypt(value, key) {
 /**
 * 使用 HMAC-SHA-384 认证文本或字节，并返回十六进制标签。
 *
-* @param value - 要认证的 UTF-8 文本或原始字节。
-* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
-* @returns 96 个小写十六进制字符组成的认证标签。
+* @param value - 要认证的 UTF-8 文本或原始字节
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节
+* @returns 96 个小写十六进制字符组成的认证标签
 */
 async function HMACSHA384Encrypt(value, key) {
 	return toLowerHex(await computeHmacBytes(value, key, "SHA-384"));
@@ -2508,9 +2506,9 @@ async function HMACSHA384Encrypt(value, key) {
 /**
 * 使用 HMAC-SHA-512 认证文本或字节，并返回十六进制标签。
 *
-* @param value - 要认证的 UTF-8 文本或原始字节。
-* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
-* @returns 128 个小写十六进制字符组成的认证标签。
+* @param value - 要认证的 UTF-8 文本或原始字节
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节
+* @returns 128 个小写十六进制字符组成的认证标签
 */
 async function HMACSHA512Encrypt(value, key) {
 	return toLowerHex(await computeHmacBytes(value, key, "SHA-512"));
@@ -2518,18 +2516,18 @@ async function HMACSHA512Encrypt(value, key) {
 /**
 * 使用 PBKDF2-HMAC-SHA-256 从密码派生密钥。
 *
-* @param password - 1 至 1,024 UTF-8 字节的密码。
-* @param salt - 至少 8 字节的盐。
+* @param password - 1 至 1,024 UTF-8 字节的密码
+* @param salt - 至少 8 字节的盐
 * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
-* @param outputLength - 输出长度，范围为 1 至 1,024 字节。
-* @returns 指定长度的派生密钥。
+* @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("PBKDF2 盐值必须至少包含 8 字节，建议不少于 16 字节。");
-	if (!Number.isSafeInteger(outputLength) || outputLength < 1 || outputLength > 1024) throw new RangeError("`outputLength` 必须是 1 到 1,024 之间的安全整数。");
-	const crypto = requireWebCrypto();
+	if (salt.length < 8) throw new RangeError("The PBKDF2 salt must contain at least 8 bytes; at least 16 bytes are recommended.");
+	if (!Number.isSafeInteger(outputLength) || outputLength < 1 || outputLength > 1024) throw new RangeError("`outputLength` must be a safe integer between 1 and 1,024.");
+	assertWebCrypto("importKey", "deriveBits");
 	const material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveBits"]);
 	const derived = await crypto.subtle.deriveBits({
 		hash: "SHA-256",
@@ -2542,7 +2540,7 @@ async function PBKDF2SHA256(password, salt, iterations = defaultPbkdf2Iterations
 /**
 * 生成可持久化的随机盐 PBKDF2-HMAC-SHA-256 密码哈希。
 *
-* @param password - 1 至 1,024 UTF-8 字节的密码。
+* @param password - 1 至 1,024 UTF-8 字节的密码
 * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
 * @returns 包含版本、迭代次数、16 字节随机盐和 32 字节派生密钥的自描述字符串。
 */
@@ -2559,7 +2557,7 @@ async function HashPasswordPBKDF2SHA256(password, iterations = defaultPbkdf2Iter
 /**
 * 验证 {@link HashPasswordPBKDF2SHA256} 生成的密码哈希。
 *
-* @param password - 要验证的密码。
+* @param password - 要验证的密码
 * @param passwordHash - 自描述的 PBKDF2-HMAC-SHA-256 密码哈希。
 * @returns 格式有效且密码匹配时返回 `true`；格式无效或密码错误时返回 `false`。
 */
@@ -2581,13 +2579,13 @@ async function VerifyPasswordPBKDF2SHA256(password, passwordHash) {
 *
 * @param inputKeyMaterial - 输入密钥材料，例如 ECDH 原始共享秘密。
 * @param salt - 可选盐；空值按 RFC 5869 的零盐语义处理。
-* @param info - 应用、协议和密钥用途上下文。
-* @param outputLength - 输出长度，范围为 1 至 8,160 字节。
-* @returns 与 `salt` 和 `info` 绑定的派生密钥。
+* @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` 必须是 1 到 8,160 之间的安全整数。");
-	const crypto = requireWebCrypto();
+	if (!Number.isSafeInteger(outputLength) || outputLength < 1 || outputLength > 8160) throw new RangeError("`outputLength` must be a safe integer between 1 and 8,160.");
+	assertWebCrypto("importKey", "deriveBits");
 	const material = await crypto.subtle.importKey("raw", toArrayBuffer(inputKeyMaterial), "HKDF", false, ["deriveBits"]);
 	const derived = await crypto.subtle.deriveBits({
 		hash: "SHA-256",
@@ -2603,10 +2601,10 @@ async function HKDFSHA256(inputKeyMaterial, salt = /* @__PURE__ */ new Uint8Arra
 * @remarks 密钥和 IV 分别补字符 `f` 或截断到 32、16 个 UTF-16 Code Unit，与 .NET
 * `AESEncrypt` 保持一致。CBC/ECB 不提供完整性认证，密文可能被篡改。
 * @param dataStr - 要加密的 UTF-8 文本；空白文本返回 `null`。
-* @param key - 非空白的密钥文本。
+* @param key - 非空白的密钥文本
 * @param vector - 非空白的初始化向量文本；ECB 模式仍要求传入该参数以对齐 .NET 签名。
-* @param cipherMode - AES 分组模式，默认 `CBC`。
-* @param paddingMode - AES 填充模式，默认 `PKCS7`。
+* @param cipherMode - AES 分组模式，默认 `CBC`
+* @param paddingMode - AES 填充模式，默认 `PKCS7`
 * @returns Base64 密文；输入、密钥或 IV 为空白时返回 `null`。
 * @throws 模式或填充不受支持时抛出 `RangeError`。
 */
@@ -2628,9 +2626,9 @@ function AESEncrypt(dataStr, key, vector, cipherMode = "CBC", paddingMode = "PKC
 		case "ISO10126":
 			padding = import_pad_iso10126.default;
 			break;
-		default: throw new RangeError("不支持当前 `paddingMode`。");
+		default: throw new RangeError("Unsupported `paddingMode`.");
 	}
-	if (paddingMode === "None" && encodeUtf8(dataStr).length % 16 !== 0) throw new RangeError("当 `paddingMode` 为 `None` 时，AES 明文长度必须是 16 字节的整数倍。");
+	if (paddingMode === "None" && encodeUtf8(dataStr).length % 16 !== 0) throw new RangeError("AES plaintext length must be a multiple of 16 bytes when `paddingMode` is `None`.");
 	const keyBytes = import_enc_utf8.default.parse(key.padEnd(32, "f").slice(0, 32));
 	const vectorBytes = import_enc_utf8.default.parse(vector.padEnd(16, "f").slice(0, 16));
 	return import_aes.default.encrypt(dataStr, keyBytes, cipherMode === "CBC" ? {
@@ -2647,10 +2645,10 @@ function AESEncrypt(dataStr, key, vector, cipherMode = "CBC", paddingMode = "PKC
 *
 * @remarks 参数归一化规则与 {@link AESEncrypt} 以及 .NET `AESDecrypt` 相同。
 * @param dataStr - Base64 密文；空白文本返回 `null`。
-* @param key - 加密时使用的密钥文本。
-* @param vector - 加密时使用的初始化向量文本。
-* @param cipherMode - AES 分组模式，默认 `CBC`。
-* @param paddingMode - AES 填充模式，默认 `PKCS7`。
+* @param key - 加密时使用的密钥文本
+* @param vector - 加密时使用的初始化向量文本
+* @param cipherMode - AES 分组模式，默认 `CBC`
+* @param paddingMode - AES 填充模式，默认 `PKCS7`
 * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串；输入、密钥或 IV 为空白时返回 `null`。
 * @throws 模式、填充、Base64、密钥或密文无效时抛出错误。
 */
@@ -2672,10 +2670,10 @@ function AESDecrypt(dataStr, key, vector, cipherMode = "CBC", paddingMode = "PKC
 		case "ISO10126":
 			padding = import_pad_iso10126.default;
 			break;
-		default: throw new RangeError("不支持当前 `paddingMode`。");
+		default: throw new RangeError("Unsupported `paddingMode`.");
 	}
 	const ciphertextBytes = decodeBase64Bytes(dataStr);
-	if (ciphertextBytes.length === 0 || ciphertextBytes.length % 16 !== 0) throw new RangeError("AES 密文必须至少包含一个完整的 16 字节块。");
+	if (ciphertextBytes.length === 0 || ciphertextBytes.length % 16 !== 0) throw new RangeError("AES ciphertext must contain at least one complete 16-byte block.");
 	const keyBytes = import_enc_utf8.default.parse(key.padEnd(32, "f").slice(0, 32));
 	const vectorBytes = import_enc_utf8.default.parse(vector.padEnd(16, "f").slice(0, 16));
 	return createDecodedText(import_aes.default.decrypt(dataStr, keyBytes, cipherMode === "CBC" ? {
@@ -2691,14 +2689,14 @@ function AESDecrypt(dataStr, key, vector, cipherMode = "CBC", paddingMode = "PKC
 * 使用 SHA-256 归一化文本密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
 *
 * @remarks 输出与 .NET `AESEncryptAuthenticated` 的 v1 Base64 二进制载荷完全一致。
-* @param plaintext - 要加密的 UTF-8 文本。
+* @param plaintext - 要加密的 UTF-8 文本
 * @param key - 非空的 UTF-8 文本密钥；内部归一化为 32 字节 SHA-256 摘要。
-* @returns Base64 编码的 v1 AES-GCM 认证载荷。
+* @returns Base64 编码的 v1 AES-GCM 认证载荷
 * @throws 密钥为空或运行时缺少 Web Crypto 时抛出错误。
 */
 async function AESEncryptAuthenticated(plaintext, key) {
-	if (key.trim().length === 0) throw new TypeError("加密密钥不能为空。");
-	const crypto = requireWebCrypto();
+	if (key.trim().length === 0) throw new TypeError("The encryption key must not be empty.");
+	assertWebCrypto("importKey", "encrypt");
 	const keyBytes = await SHA256Bytes(key);
 	const cryptoKey = await crypto.subtle.importKey("raw", toArrayBuffer(keyBytes), { name: "AES-GCM" }, false, ["encrypt"]);
 	const nonce = GenerateRandomBytes(12);
@@ -2719,21 +2717,21 @@ async function AESEncryptAuthenticated(plaintext, key) {
 * 解密并认证 .NET `AESEncryptAuthenticated` 或 {@link AESEncryptAuthenticated} 生成的载荷。
 *
 * @param payload - Base64 编码的 v1 AES-GCM 二进制载荷。
-* @param key - 加密时使用的非空 UTF-8 文本密钥。
+* @param key - 加密时使用的非空 UTF-8 文本密钥
 * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串。
 * @throws 载荷格式无效、密钥错误或认证失败时抛出错误。
 */
 async function AESDecryptAuthenticated(payload, key) {
-	if (key.trim().length === 0) throw new TypeError("加密密钥不能为空。");
+	if (key.trim().length === 0) throw new TypeError("The encryption key must not be empty.");
 	const decoded = decodeBase64Bytes(payload);
-	if (decoded.length < 29 || decoded[0] !== authenticatedAesPayloadVersion) throw new TypeError("不支持该 AES-GCM 载荷格式或版本。");
+	if (decoded.length < 29 || decoded[0] !== authenticatedAesPayloadVersion) throw new TypeError("Unsupported AES-GCM payload format or version.");
 	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();
+	assertWebCrypto("importKey", "decrypt");
 	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({
@@ -2741,7 +2739,7 @@ async function AESDecryptAuthenticated(payload, key) {
 		name: "AES-GCM",
 		tagLength: 128
 	}, cryptoKey, toArrayBuffer(ciphertextAndTag));
-	return createDecodedText(getTextDecoder().decode(plaintext));
+	return createDecodedText(decodeUtf8(plaintext));
 }
 /**
 * 使用 PBKDF2-HMAC-SHA-256 派生密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
@@ -2749,18 +2747,18 @@ async function AESDecryptAuthenticated(payload, key) {
 * @remarks 每次调用生成独立 16 字节盐与 12 字节 IV。输出是与 .NET `AESEncryptWithPassword`
 * 一致的 v1 自描述载荷，不应由业务代码手动拆分或修改。密码加密不替代密钥管理。
 * @param plaintext - 原始文本，不进行 JSON 推断；UTF-8 编码后最大 8 MiB。
-* @param password - 1 至 1024 UTF-8 字节的秘密口令。
-* @param iterations - PBKDF2 工作因子，默认 600,000。
+* @param password - 1 至 1024 UTF-8 字节的秘密口令
+* @param iterations - PBKDF2 工作因子，默认 600,000
 * @returns 认证密文字符串；相同输入每次产生不同结果。
 * @throws 口令非法时抛出 `TypeError` 或 `RangeError`；明文过大时抛出 `RangeError`；
-* 运行时缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+* 运行时缺少 Web Crypto 时抛出 `Error`。
 */
 async function AESEncryptWithPassword(plaintext, password, iterations = defaultPbkdf2Iterations) {
 	const passwordBytes = encodeValidatedPassword(password);
 	const plaintextBytes = encodeUtf8(plaintext);
-	if (plaintextBytes.length > maximumPlaintextBytes) throw new RangeError(`UTF-8 明文不能超过 ${maximumPlaintextBytes} 字节。`);
+	if (plaintextBytes.length > maximumPlaintextBytes) throw new RangeError(`The UTF-8 plaintext must not exceed ${maximumPlaintextBytes} bytes.`);
 	const validatedIterations = validateIterations(iterations);
-	const crypto = requireWebCrypto();
+	assertWebCrypto("importKey", "deriveKey", "encrypt");
 	const salt = GenerateRandomBytes(16);
 	const iv = GenerateRandomBytes(12);
 	const material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveKey"]);
@@ -2790,17 +2788,17 @@ async function AESEncryptWithPassword(plaintext, password, iterations = defaultP
 /**
 * 解密 {@link AESEncryptWithPassword} 生成的 v1 认证载荷。
 *
-* @param payload - 未修改的 v1 载荷，最大约 16 MiB 文本。
-* @param password - 加密时使用的口令。
+* @param payload - 未修改的 v1 载荷，最大约 16 MiB 文本
+* @param password - 加密时使用的口令
 * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串。
 * @throws 格式或字段非法时抛出 `TypeError`，载荷过大时抛出 `RangeError`，认证或密码
 * 失败及缺少平台能力时抛出 `Error`。
 */
 async function AESDecryptWithPassword(payload, password) {
 	const passwordBytes = encodeValidatedPassword(password);
-	if (payload.length > maximumPayloadLength) throw new RangeError("加密载荷超出支持的大小。");
+	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("不支持该加密载荷格式。");
+	if (parts.length !== 5 || parts[0] !== encryptedPayloadPrefix) throw new TypeError("Unsupported encrypted payload format.");
 	let iterations;
 	let salt;
 	let iv;
@@ -2810,12 +2808,11 @@ async function AESDecryptWithPassword(payload, password) {
 		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("加密载荷的字段长度无效。");
+		if (salt.length !== 16 || iv.length !== 12 || ciphertext.length < 16) throw new TypeError("The encrypted payload contains invalid field lengths.");
 	} catch (cause) {
-		throw new TypeError("加密载荷包含无效字段。", { cause });
+		throw new TypeError("The encrypted payload contains invalid fields.", { cause });
 	}
-	const crypto = requireWebCrypto();
-	const textDecoder = getTextDecoder();
+	assertWebCrypto("importKey", "deriveKey", "decrypt");
 	try {
 		const material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveKey"]);
 		const key = await crypto.subtle.deriveKey({
@@ -2833,9 +2830,9 @@ async function AESDecryptWithPassword(payload, password) {
 			name: "AES-GCM",
 			tagLength: 128
 		}, key, toArrayBuffer(ciphertext));
-		return createDecodedText(textDecoder.decode(plaintext));
+		return createDecodedText(decodeUtf8(plaintext));
 	} catch (cause) {
-		throw new Error("无法认证或解密载荷。", { cause });
+		throw new Error("Unable to authenticate or decrypt the payload.", { cause });
 	}
 }
 /**
@@ -2846,8 +2843,8 @@ async function AESDecryptWithPassword(payload, password) {
 * @throws 模数小于 2,048 或不是 256 的倍数时抛出 `RangeError`。
 */
 async function GenerateRSAKeyPair(modulusLength = 2048) {
-	if (!Number.isSafeInteger(modulusLength) || modulusLength < 2048 || modulusLength % 256 !== 0) throw new RangeError("`modulusLength` 必须是大于或等于 2048 且能被 256 整除的安全整数。");
-	const crypto = requireWebCrypto();
+	if (!Number.isSafeInteger(modulusLength) || modulusLength < 2048 || modulusLength % 256 !== 0) throw new RangeError("`modulusLength` must be a safe integer of at least 2048 divisible by 256.");
+	assertWebCrypto("generateKey", "exportKey");
 	const keyPair = assertKeyPair(await crypto.subtle.generateKey({
 		hash: "SHA-256",
 		modulusLength,
@@ -2861,11 +2858,11 @@ async function GenerateRSAKeyPair(modulusLength = 2048) {
 *
 * @param plaintext - 要加密的 UTF-8 文本；长度必须满足 RSA-OAEP 模数限制。
 * @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
-* @returns Base64 编码的 RSA 密文。
+* @returns Base64 编码的 RSA 密文
 * @throws 公钥格式无效或明文超过 RSA-OAEP 容量时抛出错误。
 */
 async function RSAEncryptOAEP(plaintext, publicKeyPem) {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("importKey", "encrypt");
 	const key = await crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
 		hash: "SHA-256",
 		name: "RSA-OAEP"
@@ -2876,30 +2873,30 @@ async function RSAEncryptOAEP(plaintext, publicKeyPem) {
 /**
 * 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。
 *
-* @param ciphertext - Base64 编码的 RSA 密文。
-* @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+* @param ciphertext - Base64 编码的 RSA 密文
+* @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥
 * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串。
 * @throws 私钥、Base64 或密文无效时抛出错误。
 */
 async function RSADecryptOAEP(ciphertext, privateKeyPem) {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("importKey", "decrypt");
 	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 createDecodedText(getTextDecoder().decode(plaintext));
+	return createDecodedText(decodeUtf8(plaintext));
 }
 /**
 * 使用 RSA-PSS/SHA-256 私钥签名文本或字节。
 *
-* @param value - 要签名的 UTF-8 文本或原始字节。
-* @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+* @param value - 要签名的 UTF-8 文本或原始字节
+* @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥
 * @returns Base64 编码的 RSA-PSS 签名；盐长度固定为 32 字节。
 * @throws 私钥格式无效或签名失败时抛出错误。
 */
 async function RSASignPSS(value, privateKeyPem) {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("importKey", "sign");
 	const key = await crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
 		hash: "SHA-256",
 		name: "RSA-PSS"
@@ -2913,14 +2910,14 @@ async function RSASignPSS(value, privateKeyPem) {
 /**
 * 使用 RSA-PSS/SHA-256 公钥验证 Base64 签名。
 *
-* @param value - 签名时使用的 UTF-8 文本或原始字节。
-* @param signature - Base64 编码的 RSA-PSS 签名。
+* @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();
+	assertWebCrypto("importKey", "verify");
 	const key = await crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
 		hash: "SHA-256",
 		name: "RSA-PSS"
@@ -2937,7 +2934,7 @@ async function RSAVerifyPSS(value, signature, publicKeyPem) {
 * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
 */
 async function GenerateECDSAKeyPair(namedCurve = "P-256") {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("generateKey", "exportKey");
 	const keyPair = assertKeyPair(await crypto.subtle.generateKey({
 		name: "ECDSA",
 		namedCurve
@@ -2948,13 +2945,13 @@ async function GenerateECDSAKeyPair(namedCurve = "P-256") {
 * 使用 ECDSA 私钥签名文本或字节。
 *
 * @remarks Web Crypto 返回 IEEE P1363 固定字段拼接格式，与 .NET 实现一致。
-* @param value - 要签名的 UTF-8 文本或原始字节。
-* @param privateKeyPem - 未加密的 EC PKCS#8 PEM 私钥。
-* @param namedCurve - 私钥使用的 NIST 曲线。
+* @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();
+	assertWebCrypto("importKey", "sign");
 	const key = await crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
 		name: "ECDSA",
 		namedCurve
@@ -2969,14 +2966,14 @@ async function ECDSASign(value, privateKeyPem, namedCurve = "P-256") {
 /**
 * 使用 ECDSA 公钥验证 Base64 签名。
 *
-* @param value - 签名时使用的 UTF-8 文本或原始字节。
+* @param value - 签名时使用的 UTF-8 文本或原始字节
 * @param signature - Base64 编码的 IEEE P1363 ECDSA 签名。
 * @param publicKeyPem - EC SubjectPublicKeyInfo PEM 公钥。
-* @param namedCurve - 公钥使用的 NIST 曲线。
+* @param namedCurve - 公钥使用的 NIST 曲线
 * @returns 签名与内容、公钥和曲线匹配时返回 `true`。
 */
 async function ECDSAVerify(value, signature, publicKeyPem, namedCurve = "P-256") {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("importKey", "verify");
 	const key = await crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
 		name: "ECDSA",
 		namedCurve
@@ -2994,7 +2991,7 @@ async function ECDSAVerify(value, signature, publicKeyPem, namedCurve = "P-256")
 * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
 */
 async function GenerateECDHKeyPair(namedCurve = "P-256") {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("generateKey", "exportKey");
 	const keyPair = assertKeyPair(await crypto.subtle.generateKey({
 		name: "ECDH",
 		namedCurve
@@ -3005,13 +3002,13 @@ async function GenerateECDHKeyPair(namedCurve = "P-256") {
 * 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
 *
 * @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
-* @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+* @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥
 * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
-* @param namedCurve - 双方密钥使用的 NIST 曲线。
-* @returns 曲线字段长度的原始 ECDH 共享秘密。
+* @param namedCurve - 双方密钥使用的 NIST 曲线
+* @returns 曲线字段长度的原始 ECDH 共享秘密
 */
 async function DeriveECDHSecret(privateKeyPem, publicKeyPem, namedCurve = "P-256") {
-	const crypto = requireWebCrypto();
+	assertWebCrypto("importKey", "deriveBits");
 	const [privateKey, publicKey] = await Promise.all([crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
 		name: "ECDH",
 		namedCurve
@@ -3030,14 +3027,15 @@ async function DeriveECDHSecret(privateKeyPem, publicKeyPem, namedCurve = "P-256
 * 使用 ECDH 后以 SHA-256 派生共享密钥。
 *
 * @remarks 相比直接使用原始共享秘密，此入口与 .NET `DeriveECDHKeySHA256` 一致并固定输出 32 字节。
-* @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+* @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥
 * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
-* @param namedCurve - 双方密钥使用的 NIST 曲线。
-* @returns 32 字节共享密钥。
+* @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));
+	assertWebCrypto("digest");
+	const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(secret));
 	return new Uint8Array(digest);
 }
 //#endregion