@fast-china/utils 2.0.0 → 2.0.2

package/dist/crypto/index.mjs

@@ -1,21 +1,37 @@
 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;
 /**
 * 获取安全随机数能力。
@@ -42,13 +58,6 @@ const requireWebCrypto = () => {
 	return crypto;
 };
 /**
-* 把二进制联合输入规范为字节。
-*
-* @param value - UTF-8 文本或现有字节数组。
-* @returns 文本的新编码结果，或原始字节数组引用。
-*/
-const toInputBytes = (value) => typeof value === "string" ? encodeUtf8(value) : value;
-/**
 * 把 Uint8Array 复制为独立的完整 ArrayBuffer。
 *
 * @remarks 不能直接返回 `bytes.buffer`，因为输入可能只是更大 Buffer 的切片。
@@ -118,46 +127,6 @@ const assertKeyPair = (value) => {
 	throw new Error("The runtime did not generate a key pair.");
 };
 /**
-* 按旧协议规范化 AES Key。
-*
-* @param key - 任意长度 UTF-8 文本 Key。
-* @returns 补字符 `f` 或截断到 32 个 UTF-16 Code Unit 后的 CryptoJS WordArray。
-*/
-const normalizeAesKey = (key) => Utf8.parse(key.padEnd(32, "f").slice(0, 32));
-/**
-* 按旧协议规范化 AES IV。
-*
-* @param vector - 任意长度 UTF-8 文本 IV。
-* @returns 补字符 `f` 或截断到 16 个 UTF-16 Code Unit 后的 CryptoJS WordArray。
-*/
-const normalizeAesVector = (vector) => Utf8.parse(vector.padEnd(16, "f").slice(0, 16));
-/**
-* 选择与 ECDSA 曲线对应的摘要算法。
-*
-* @param namedCurve - 本模块支持的 NIST 曲线。
-* @returns P-256、P-384、P-521 分别对应 SHA-256、SHA-384、SHA-512。
-*/
-const getEcdsaHash = (namedCurve) => {
-	switch (namedCurve) {
-		case "P-256": return "SHA-256";
-		case "P-384": return "SHA-384";
-		case "P-521": return "SHA-512";
-	}
-};
-/**
-* 获取 ECDH 共享秘密的导出位数。
-*
-* @param namedCurve - 本模块支持的 NIST 曲线。
-* @returns 曲线字段按完整字节对齐后的位数；P-521 返回 528。
-*/
-const getEcBitLength = (namedCurve) => {
-	switch (namedCurve) {
-		case "P-256": return 256;
-		case "P-384": return 384;
-		case "P-521": return 528;
-	}
-};
-/**
 * 校验并编码密码。
 *
 * @param password - 用户提供的密码文本。
@@ -182,28 +151,30 @@ 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();
 /**
-* 从密码派生 AES-256-GCM Key。
+* 使用指定的 Web Crypto HMAC 算法计算原始认证标签。
 *
-* @param passwordBytes - 已校验的 UTF-8 密码。
-* @param salt - 载荷中保存的 16 字节随机盐。
-* @param iterations - 已校验 PBKDF2 成本。
-* @param usage - 派生 Key 唯一允许的加密或解密用途。
-* @returns 不可导出的 AES-GCM CryptoKey。
-* @throws `Error` 当平台缺少相应 Web Crypto 能力或拒绝派生。
+* @param value - 要认证的 UTF-8 文本或原始字节。
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+* @param hash - HMAC 使用的 SHA-2 摘要算法。
+* @returns 算法规定长度的原始认证标签。
+* @throws `TypeError` 当密钥为空。
+* @throws `Error` 当运行时缺少所需 Web Crypto 能力。
 */
-const derivePasswordEncryptionKey = async (passwordBytes, salt, iterations, usage) => {
+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 material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveKey"]);
-	return crypto.subtle.deriveKey({
-		hash: "SHA-256",
-		iterations,
-		name: "PBKDF2",
-		salt: toArrayBuffer(salt)
-	}, material, {
-		length: 256,
-		name: "AES-GCM"
-	}, false, [usage]);
+	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);
 };
 /**
 * 生成安全随机字节。
@@ -212,11 +183,46 @@ const derivePasswordEncryptionKey = async (passwordBytes, salt, iterations, usag
 * @returns 新建的 `Uint8Array`。
 * @throws 参数非法时抛出 `RangeError`；缺少 Web Crypto 时抛出 `Error`。
 */
-function generateRandomBytes(length) {
+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 是快速摘要，不适合直接存储或校验密码。
@@ -224,222 +230,346 @@ function generateRandomBytes(length) {
 * @returns 32 字节摘要。
 * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
 */
-async function sha256Bytes(value) {
-	const digest = await requireWebCrypto().subtle.digest("SHA-256", toArrayBuffer(toInputBytes(value)));
+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 字符小写十六进制文本。
+* @returns 64 字符大写十六进制文本。
 * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
 */
-async function sha256Hex(value) {
-	const digest = await sha256Bytes(value);
-	return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+async function SHA256Encrypt(value) {
+	return toUpperHex(await SHA256Bytes(value));
 }
 /**
-* 计算 MD5 摘要并返回小写十六进制文本。
+* 计算 SHA-384 摘要。
 *
-* @remarks MD5 仅用于历史协议和非安全校验，不得用于密码、签名或抗碰撞场景。
-* @param value - UTF-8 文本。
-* @returns 32 字符小写十六进制摘要。
+* @param value - UTF-8 文本或原始字节。
+* @returns 48 字节摘要。
 */
-function md5Hex(value) {
-	return MD5(value).toString(Hex);
+async function SHA384Bytes(value) {
+	const digest = await requireWebCrypto().subtle.digest("SHA-384", toArrayBuffer(encodeUtf8(value)));
+	return new Uint8Array(digest);
 }
 /**
-* 计算 SHA-1 摘要并返回小写十六进制文本。
+* 计算 SHA-384 并格式化为十六进制文本。
 *
-* @remarks SHA-1 仅用于旧系统互通；新用途应使用 {@link sha256Hex}。
-* @param value - UTF-8 文本。
-* @returns 40 字符小写十六进制摘要。
+* @param value - UTF-8 文本或原始字节。
+* @returns 96 个大写十六进制字符组成的摘要。
 */
-function sha1Hex(value) {
-	return SHA1(value).toString(Hex);
+async function SHA384Encrypt(value) {
+	return toUpperHex(await SHA384Bytes(value));
 }
 /**
-* 使用 AES-256-CBC 与 PKCS#7 填充加密文本。
+* 计算 SHA-512 摘要。
 *
-* @remarks 密钥按 UTF-8 文本补齐或截断为 32 个字符，IV 补齐或截断为 16 个字符。
-* 该格式不包含认证标签；新数据优先使用 {@link encryptTextWithPassword}。
-* @param plaintext - UTF-8 明文。
-* @param key - 兼容密钥文本。
-* @param vector - 兼容初始化向量文本。
-* @returns CryptoJS Base64 密文。
+* @param value - UTF-8 文本或原始字节。
+* @returns 64 字节摘要。
 */
-function encryptLegacyAesCbc(plaintext, key, vector) {
-	if (plaintext.length === 0) return "";
-	return AES.encrypt(plaintext, normalizeAesKey(key), {
-		iv: normalizeAesVector(vector),
-		padding: Pkcs7
-	}).toString();
+async function SHA512Bytes(value) {
+	const digest = await requireWebCrypto().subtle.digest("SHA-512", toArrayBuffer(encodeUtf8(value)));
+	return new Uint8Array(digest);
 }
-/** 解密 {@link encryptLegacyAesCbc} 生成的 CryptoJS Base64 密文。 */
-function decryptLegacyAesCbc(ciphertext, key, vector) {
-	if (ciphertext.length === 0) return "";
-	return AES.decrypt(ciphertext, normalizeAesKey(key), {
-		iv: normalizeAesVector(vector),
-		padding: Pkcs7
-	}).toString(Utf8);
+/**
+* 计算 SHA-512 并格式化为十六进制文本。
+*
+* @param value - UTF-8 文本或原始字节。
+* @returns 128 个大写十六进制字符组成的摘要。
+*/
+async function SHA512Encrypt(value) {
+	return toUpperHex(await SHA512Bytes(value));
 }
 /**
-* 使用 AES-256-ECB 与 PKCS#7 填充加密文本。
+* 使用 HMAC-SHA-256 认证文本，并返回十六进制标签。
 *
-* @remarks ECB 会暴露重复明文块结构，只能用于必须兼容的旧协议，不得用于新数据设计。
-* @param plaintext - UTF-8 明文。
-* @param key - 兼容密钥文本，补齐或截断为 32 个字符。
-* @returns CryptoJS Base64 密文。
+* @param value - 要认证的 UTF-8 文本或原始字节。
+* @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+* @returns 64 个小写十六进制字符组成的认证标签。
 */
-function encryptLegacyAesEcb(plaintext, key) {
-	if (plaintext.length === 0) return "";
-	return AES.encrypt(plaintext, normalizeAesKey(key), {
-		mode: ECB,
-		padding: Pkcs7
-	}).toString();
+async function HMACSHA256Encrypt(value, key) {
+	return toLowerHex(await computeHmacBytes(value, key, "SHA-256"));
 }
-/** 解密 {@link encryptLegacyAesEcb} 生成的 CryptoJS Base64 密文。 */
-function decryptLegacyAesEcb(ciphertext, key) {
-	if (ciphertext.length === 0) return "";
-	return AES.decrypt(ciphertext, normalizeAesKey(key), {
-		mode: ECB,
-		padding: Pkcs7
-	}).toString(Utf8);
+/**
+* 使用 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"));
 }
-/** 生成可导出的 RSA-OAEP/SHA-256 PEM 密钥对。 */
-async function generateRsaOaepKeyPair(options = {}) {
-	const modulusLength = options.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);
+/**
+* 使用 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"));
 }
-/** 使用 RSA-OAEP/SHA-256 公钥加密 UTF-8 文本，并返回 Base64 密文。 */
-async function encryptRsaOaep(plaintext, publicKeyPem) {
+/**
+* 使用 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 key = await crypto.subtle.importKey("spki", fromPem(publicKeyPem, pemLabels.public), {
+	const material = await crypto.subtle.importKey("raw", toArrayBuffer(passwordBytes), "PBKDF2", false, ["deriveBits"]);
+	const derived = await crypto.subtle.deriveBits({
 		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));
+		iterations: validateIterations(iterations),
+		name: "PBKDF2",
+		salt: toArrayBuffer(salt)
+	}, material, outputLength * 8);
+	return new Uint8Array(derived);
 }
-/** 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。 */
-async function decryptRsaOaep(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);
+/**
+* 生成可持久化的随机盐 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(":");
 }
-/** 生成 ECDSA 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);
+/**
+* 验证 {@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;
+	}
 }
-/** 使用 ECDSA 私钥签名文本或字节，并返回 Base64 签名。 */
-async function signEcdsa(value, privateKeyPem, namedCurve = "P-256") {
+/**
+* 使用 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 key = await crypto.subtle.importKey("pkcs8", fromPem(privateKeyPem, pemLabels.private), {
-		name: "ECDSA",
-		namedCurve
-	}, false, ["sign"]);
-	const signature = await crypto.subtle.sign({
-		hash: getEcdsaHash(namedCurve),
-		name: "ECDSA"
-	}, key, toArrayBuffer(toInputBytes(value)));
-	return encodeBase64Bytes(new Uint8Array(signature));
+	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);
 }
-/** 使用 ECDSA 公钥验证 Base64 签名。 */
-async function verifyEcdsa(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"]);
-	return crypto.subtle.verify({
-		hash: getEcdsaHash(namedCurve),
-		name: "ECDSA"
-	}, key, toArrayBuffer(decodeBase64Bytes(signature)), toArrayBuffer(toInputBytes(value)));
+/**
+* 使用 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();
 }
-/** 生成 ECDH 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);
+/**
+* 使用 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);
 }
 /**
-* 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
+* 使用 SHA-256 归一化文本密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
 *
-* @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
+* @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 deriveEcdhSecret(privateKeyPem, publicKeyPem, namedCurve = "P-256") {
+async function AESEncryptAuthenticated(plaintext, key) {
+	if (key.trim().length === 0) throw new TypeError("The encryption key cannot be empty.");
 	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 secret = await crypto.subtle.deriveBits({
-		name: "ECDH",
-		public: publicKey
-	}, privateKey, getEcBitLength(namedCurve));
-	return new Uint8Array(secret);
+	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} 生成的载荷。
 *
-* @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
-* 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
-* @param left - 第一字节序列。
-* @param right - 第二字节序列。
-* @returns 长度和每个字节均相同时返回 `true`。
+* @param payload - Base64 编码的 v1 AES-GCM 二进制载荷。
+* @param key - 加密时使用的非空 UTF-8 文本密钥。
+* @returns 通过认证的 UTF-8 明文。
+* @throws 载荷格式无效、密钥错误或认证失败时抛出错误。
 */
-function areBytesEqualWithoutEarlyExit(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;
+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。输出是本库 v2 自描述载荷，
-* 不应被拆分、修改或当作跨语言标准格式。密码加密不替代密钥管理；长期高价值数据
-* 应使用平台 KMS 或专门的加密方案。
+* @remarks 每次调用生成独立 16 字节盐与 12 字节 IV。输出是与 .NET `AESEncryptWithPassword`
+* 一致的 v2 自描述载荷，不应由业务代码手动拆分或修改。密码加密不替代密钥管理。
 * @param plaintext - 原始文本，不进行 JSON 推断；UTF-8 编码后最大 8 MiB。
 * @param password - 1 至 1024 UTF-8 字节的秘密口令。
-* @param options - PBKDF2 工作因子。
+* @param iterations - PBKDF2 工作因子，默认 600,000。
 * @returns 认证密文字符串；相同输入每次产生不同结果。
 * @throws 口令非法时抛出 `TypeError` 或 `RangeError`；明文过大时抛出 `RangeError`；
 * 运行时缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
 */
-async function encryptTextWithPassword(plaintext, password, options = {}) {
+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 iterations = validateIterations(options.iterations ?? defaultPbkdf2Iterations);
+	const validatedIterations = validateIterations(iterations);
 	const crypto = requireWebCrypto();
-	const salt = generateRandomBytes(16);
-	const iv = generateRandomBytes(12);
-	const key = await derivePasswordEncryptionKey(passwordBytes, salt, iterations, "encrypt");
+	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),
@@ -448,14 +578,14 @@ async function encryptTextWithPassword(plaintext, password, options = {}) {
 	}, key, plaintextBytes);
 	return [
 		encryptedPayloadPrefix,
-		String(iterations),
+		String(validatedIterations),
 		encodeBase64UrlBytes(salt),
 		encodeBase64UrlBytes(iv),
 		encodeBase64UrlBytes(new Uint8Array(ciphertext))
 	].join(":");
 }
 /**
-* 解密 {@link encryptTextWithPassword} 生成的 v2 认证载荷。
+* 解密 {@link AESEncryptWithPassword} 生成的 v2 认证载荷。
 *
 * @param payload - 未修改的 v2 载荷，最大约 16 MiB 文本。
 * @param password - 加密时使用的口令。
@@ -463,7 +593,7 @@ async function encryptTextWithPassword(plaintext, password, options = {}) {
 * @throws 格式或字段非法时抛出 `TypeError`，载荷过大时抛出 `RangeError`，认证或密码
 * 失败及缺少平台能力时抛出 `Error`。
 */
-async function decryptTextWithPassword(payload, password) {
+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(":");
@@ -484,7 +614,16 @@ async function decryptTextWithPassword(payload, password) {
 	const crypto = requireWebCrypto();
 	const textDecoder = getTextDecoder();
 	try {
-		const key = await derivePasswordEncryptionKey(passwordBytes, salt, iterations, "decrypt");
+		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),
@@ -497,45 +636,208 @@ async function decryptTextWithPassword(payload, password) {
 	}
 }
 /**
-* 规范化历史 AES 模式参数。
+* 生成可供 RSA-OAEP/SHA-256 与 RSA-PSS/SHA-256 共用的 PEM 密钥对。
 *
-* @param cipherMode - 公共 API 接收的未知模式值。
-* @returns 省略值和 `CBC` 返回 `CBC`，`ECB` 保持原值。
-* @throws `RangeError` 当值不是公开协议允许的字符串。
+* @param modulusLength - RSA 模数位数，默认 2,048；必须是不小于 2,048 的 256 倍数。
+* @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+* @throws 模数小于 2,048 或不是 256 的倍数时抛出 `RangeError`。
 */
-const resolveLegacyAesMode = (cipherMode) => {
-	if (cipherMode === void 0 || cipherMode === "CBC") return "CBC";
-	if (cipherMode === "ECB") return "ECB";
-	throw new RangeError("cipherMode must be \"CBC\" or \"ECB\".");
-};
-/** 解密历史 AES-CBC/ECB 字符串，并优先解析 JSON 结果。 */
-function decryptLegacyAesValue(dataStr, key, vector, cipherMode) {
-	if (dataStr.length === 0) return null;
-	try {
-		const plaintext = resolveLegacyAesMode(cipherMode) === "ECB" ? decryptLegacyAesEcb(dataStr, key) : decryptLegacyAesCbc(dataStr, key, vector);
-		if (plaintext.length === 0) return null;
-		try {
-			return JSON.parse(plaintext);
-		} catch {
-			return plaintext;
-		}
-	} catch {
-		return null;
-	}
+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);
 }
-/** 按指定 CBC/ECB 模式加密历史 AES 字符串。 */
-function encryptLegacyAes(dataStr, key, vector, cipherMode) {
-	return resolveLegacyAesMode(cipherMode) === "ECB" ? encryptLegacyAesEcb(dataStr, key) : encryptLegacyAesCbc(dataStr, key, vector);
+/**
+* 使用 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));
 }
-/** 返回历史兼容的大写 MD5 十六进制摘要。 */
-function md5UpperHex(value) {
-	return value.length === 0 ? value : md5Hex(value).toUpperCase();
+/**
+* 使用 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);
 }
-/** 返回历史兼容的大写 SHA-1 十六进制摘要。 */
-function sha1UpperHex(value) {
-	return value.length === 0 ? value : sha1Hex(value).toUpperCase();
+/**
+* 使用 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 { areBytesEqualWithoutEarlyExit, decryptLegacyAesCbc, decryptLegacyAesEcb, decryptLegacyAesValue, decryptRsaOaep, decryptTextWithPassword, deriveEcdhSecret, encryptLegacyAes, encryptLegacyAesCbc, encryptLegacyAesEcb, encryptRsaOaep, encryptTextWithPassword, generateEcdhKeyPair, generateEcdsaKeyPair, generateRandomBytes, generateRsaOaepKeyPair, md5Hex, md5UpperHex, sha1Hex, sha1UpperHex, sha256Bytes, sha256Hex, signEcdsa, verifyEcdsa };
+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