sm-crypto-wasm 0.3.1 → 0.7.1

package/dist/cms/sign.js

@@ -0,0 +1,194 @@
+/**
+ * CMS SignedData 签名（detached / attached）。
+ *
+ * 签名的计算对象是 `signedAttrs` 的 DER 编码（SET tag 0x31）——与验签层
+ * 使用完全相同的规则；`contentType` / `messageDigest` / `signingTime` 三个
+ * 属性按 DER SET OF 排序后编码。
+ *
+ * 只做 SignedData，不做 EnvelopedData / RFC 3161 时间戳。
+ *
+ * CMS SignedData signing (detached / attached).
+ *
+ * The signed object is the DER encoding of `signedAttrs` (SET tag 0x31) — exactly the
+ * same rule the verification layer uses; the `contentType` / `messageDigest` /
+ * `signingTime` attributes are encoded after DER SET OF sorting.
+ *
+ * SignedData only: no EnvelopedData, no RFC 3161 timestamping.
+ */
+import { explicit, implicit, integer, octetString, oid, parseDer, seq, setOf, time, } from '../asn1/index.js';
+import { bytesToBase64, bytesToPem, hexToBytes } from '../runtime/convert.js';
+import * as sm2 from '../sm2/index.js';
+import * as sm3 from '../sm3/index.js';
+import { parseCertificate } from '../x509/parse.js';
+import { rawSignatureToDer } from '../x509/sig.js';
+import { CmsError } from './errors.js';
+import { OID_CMS_CONTENT_TYPE, OID_CMS_DATA, OID_CMS_MESSAGE_DIGEST, OID_CMS_SIGNED_DATA, OID_CMS_SIGNING_TIME, OID_SM3, OID_SM3_WITH_SM2, } from './oids.js';
+/**
+ * 生成 CMS SignedData（单签名者）。
+ *
+ * 调用前需要预热 wasm：`await sm2.ensureLoaded(); await sm3.ensureLoaded();`
+ *
+ * @throws CmsError 缺少签名者证书或输入不合法。
+ *
+ * Builds a CMS SignedData structure (single signer).
+ *
+ * The wasm modules must be warmed up beforehand:
+ * `await sm2.ensureLoaded(); await sm3.ensureLoaded();`
+ *
+ * @throws CmsError When the signer certificate is missing or the input is invalid.
+ */
+export function signData(opts) {
+    const content = toDataBytes(opts.data);
+    const signerCertificate = resolveSignerCertificate(opts);
+    const chain = (opts.certificates ?? []).map((item) => resolveCertificate(item));
+    const certificates = dedupeCertificates([signerCertificate, ...chain]);
+    const digest = hexToBytes(sm3.hash(content), 'messageDigest');
+    const signingTime = opts.signingTime === false ? undefined : (opts.signingTime ?? new Date());
+    const attributes = [
+        attribute(OID_CMS_CONTENT_TYPE, setOf([oid(OID_CMS_DATA)])),
+        attribute(OID_CMS_MESSAGE_DIGEST, setOf([octetString(digest)])),
+    ];
+    if (signingTime !== undefined) {
+        attributes.push(attribute(OID_CMS_SIGNING_TIME, setOf([time(signingTime)])));
+    }
+    const signedAttrs = setOf(attributes);
+    const signature = hexToBytes(sm2.signWithID(opts.privateKey, signedAttrs.raw, opts.userID ?? new Uint8Array(0)), 'signature');
+    const signatureDer = rawSignatureToDer(signature);
+    const signerInfo = seq([
+        integer(1),
+        issuerAndSerialNumber(signerCertificate),
+        algorithmIdentifier(OID_SM3),
+        implicit(0, signedAttrs),
+        algorithmIdentifier(OID_SM3_WITH_SM2),
+        octetString(signatureDer),
+    ]);
+    const encapContentInfo = opts.detached === false
+        ? seq([oid(OID_CMS_DATA), explicit(0, octetString(content))])
+        : seq([oid(OID_CMS_DATA)]);
+    const signedDataChildren = [
+        integer(1),
+        setOf([algorithmIdentifier(OID_SM3)]),
+        encapContentInfo,
+    ];
+    if (certificates.length > 0) {
+        signedDataChildren.push(implicit(0, setOf(certificates.map((cert) => parseDer(cert.raw)))));
+    }
+    signedDataChildren.push(setOf([signerInfo]));
+    const signedData = seq(signedDataChildren);
+    const contentInfo = seq([oid(OID_CMS_SIGNED_DATA), explicit(0, signedData)]);
+    const der = new Uint8Array(contentInfo.raw);
+    return {
+        der,
+        pem: bytesToPem(der, 'CMS'),
+        base64: bytesToBase64(der),
+    };
+}
+// ---------- 编码辅助 ----------
+//
+// ---------- Encoding helpers ----------
+// 构造 CMS Attribute（OID + SET OF 值）。
+//
+// Builds a CMS Attribute (OID + SET OF values).
+function attribute(attrOid, values) {
+    return seq([oid(attrOid), values]);
+}
+// 构造 AlgorithmIdentifier。
+//
+// Builds an AlgorithmIdentifier.
+function algorithmIdentifier(oidValue) {
+    return seq([oid(oidValue)]);
+}
+// 构造 IssuerAndSerialNumber 签名者标识。
+//
+// Builds an IssuerAndSerialNumber signer identifier.
+function issuerAndSerialNumber(cert) {
+    let issuer;
+    try {
+        issuer = parseDer(cert.issuer.raw);
+    }
+    catch (err) {
+        throw new CmsError('signData: failed to re-encode issuer name', { cause: err });
+    }
+    return seq([issuer, integer(cert.serialNumber)]);
+}
+// ---------- 输入辅助 ----------
+//
+// ---------- Input helpers ----------
+/**
+ * 字符串按 UTF-8 处理；CMS 的 data 语义是报文内容，不是 hex。
+ *
+ * Strings are treated as UTF-8; the CMS data field carries message content, not hex.
+ */
+function toDataBytes(data) {
+    if (data instanceof Uint8Array)
+        return new Uint8Array(data);
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data);
+    throw new TypeError('signData: data must be a string or Uint8Array');
+}
+// 从 options 解析签名者证书。
+//
+// Resolves the signer certificate from options.
+function resolveSignerCertificate(opts) {
+    const input = opts.certificate ?? opts.certificates?.[0];
+    if (input === undefined) {
+        throw new CmsError('signData: certificate is required to build the SignerInfo');
+    }
+    return resolveCertificate(input);
+}
+// 把 Certificate / PEM / DER 输入统一为 Certificate。
+//
+// Normalizes Certificate / PEM / DER input.
+function resolveCertificate(input) {
+    if (isCertificateLike(input))
+        return input;
+    try {
+        return parseCertificate(input);
+    }
+    catch (err) {
+        throw new CmsError('signData: invalid certificate', { cause: err });
+    }
+}
+// 判断值是否像 Certificate。
+//
+// Checks whether a value looks like a Certificate.
+function isCertificateLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !(value instanceof Uint8Array) &&
+        'tbsCertificate' in value &&
+        'subjectPublicKey' in value);
+}
+// 按 DER 去重证书。
+//
+// Deduplicates certificates by DER.
+function dedupeCertificates(certificates) {
+    const seen = new Set();
+    const out = [];
+    for (const cert of certificates) {
+        const key = base64Key(cert.raw);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(cert);
+    }
+    return out;
+}
+// 把证书 DER 字节映射成单字节字符串，作为去重 key（只用于等值比较，不是 base64）。
+//
+// Maps certificate DER bytes to a one-code-unit-per-byte string used as a dedup key
+// (equality comparison only; this is not a base64 encoding).
+function base64Key(bytes) {
+    let key = '';
+    for (let i = 0; i < bytes.length; i++)
+        key += String.fromCharCode(bytes[i]);
+    return key;
+}
+/**
+ * 证书集合中的证书原始 DER（供外部检查）。
+ *
+ * Raw DER of each certificate in the set, for external inspection.
+ */
+export function certificateChainDer(certificates) {
+    return certificates.map((cert) => new Uint8Array(cert.raw));
+}

package/dist/cms/verify.d.ts

@@ -0,0 +1,117 @@
+/**
+ * CMS SignedData 验签。
+ *
+ * 只验证签名与 messageDigest，**不建立信任链**、不检查证书有效期/用途；
+ * 需要信任判断时由调用方对 `signers[i].certificate` 另行处理。
+ *
+ * CMS SignedData verification.
+ *
+ * Only the signature and messageDigest are checked; **no trust chain is built** and
+ * certificate validity/key usage are not examined. When a trust decision is needed, the
+ * caller handles `signers[i].certificate` separately.
+ */
+import type { Certificate } from '../x509/types.js';
+import { type CmsVerifyErrorCode } from './errors.js';
+import { type CmsSignerInfo } from './parse.js';
+/**
+ * `verifySignedData` 的选项。
+ *
+ * Options of `verifySignedData`.
+ */
+export interface VerifySignedDataOptions {
+    /**
+     * detached 模式下的原始内容（字符串按 UTF-8 编码）。
+     *
+     * The original content in detached mode (strings are treated as UTF-8).
+     */
+    readonly detachedData?: string | Uint8Array;
+    /**
+     * 额外候选证书（CMS 未内嵌签名者证书时使用）。
+     *
+     * Extra candidate certificates, used when the CMS does not embed the signer
+     * certificate.
+     */
+    readonly certificates?: readonly (Certificate | string | Uint8Array)[];
+    /**
+     * 显式指定 SM2 用户标识；省略时依次尝试空标识与 GM/T 默认标识。
+     *
+     * An explicit SM2 user identifier; when omitted, the empty identifier and then the
+     * GM/T default identifier are tried in turn.
+     */
+    readonly userID?: Uint8Array;
+}
+/**
+ * 单个签名者的验签结果。
+ *
+ * The verification result of a single signer.
+ */
+export interface VerifySignerResult {
+    /**
+     * 是否通过校验（签名 + messageDigest 均通过）。
+     *
+     * Whether both the signature and the messageDigest checks passed.
+     */
+    readonly valid: boolean;
+    /**
+     * 匹配到的签名者证书。
+     *
+     * The matched signer certificate.
+     */
+    readonly certificate?: Certificate;
+    /**
+     * signedAttrs 中的 signingTime（该属性缺失时为 `undefined`）。
+     *
+     * The signingTime from signedAttrs (`undefined` when the attribute is absent).
+     */
+    readonly signingTime?: Date;
+    /**
+     * 人类可读的补充说明。
+     *
+     * A human-readable explanation.
+     */
+    readonly error?: string;
+    /**
+     * 结构化失败原因（`valid === true` 时不存在）。
+     *
+     * The structured failure reason (absent when `valid === true`).
+     */
+    readonly errorCode?: CmsVerifyErrorCode;
+}
+/**
+ * `verifySignedData` 的结果。
+ *
+ * Result of `verifySignedData`.
+ */
+export interface VerifySignedDataResult {
+    /**
+     * 至少有一个签名者且所有签名者都通过校验。
+     *
+     * True when there is at least one signer and every signer is valid.
+     */
+    readonly valid: boolean;
+    /**
+     * 每个签名者的结果，顺序与 `signerInfos` 一致。
+     *
+     * Per-signer results, in `signerInfos` order.
+     */
+    readonly signers: readonly VerifySignerResult[];
+}
+/**
+ * 验证 CMS SignedData。
+ *
+ * 结构完全无法解析时返回 `{ valid: false, signers: [{ errorCode: 'MALFORMED' }] }`，
+ * 而不是抛错；wasm 未预热等环境错误仍会抛出。
+ *
+ * Verifies a CMS SignedData.
+ *
+ * When the structure cannot be parsed at all it returns
+ * `{ valid: false, signers: [{ errorCode: 'MALFORMED' }] }` instead of throwing;
+ * environment errors such as an unloaded wasm module are still thrown.
+ */
+export declare function verifySignedData(cms: string | Uint8Array, opts?: VerifySignedDataOptions): VerifySignedDataResult;
+/**
+ * 供调试：签名者标识的十六进制表示。
+ *
+ * For debugging: the signer identifier as hex.
+ */
+export declare function signerIdentifierHex(signer: CmsSignerInfo): string;

package/dist/cms/verify.js

@@ -0,0 +1,222 @@
+/**
+ * CMS SignedData 验签。
+ *
+ * 只验证签名与 messageDigest，**不建立信任链**、不检查证书有效期/用途；
+ * 需要信任判断时由调用方对 `signers[i].certificate` 另行处理。
+ *
+ * CMS SignedData verification.
+ *
+ * Only the signature and messageDigest are checked; **no trust chain is built** and
+ * certificate validity/key usage are not examined. When a trust decision is needed, the
+ * caller handles `signers[i].certificate` separately.
+ */
+import { bytesToHex, hexToBytes } from '../runtime/convert.js';
+import * as sm2 from '../sm2/index.js';
+import * as sm3 from '../sm3/index.js';
+import { parseCertificate } from '../x509/parse.js';
+import { derSignatureToRaw } from '../x509/sig.js';
+import { DEFAULT_SM2_USER_ID } from '../x509/verify.js';
+import { CmsError } from './errors.js';
+import { OID_CMS_CONTENT_TYPE, OID_CMS_MESSAGE_DIGEST, OID_CMS_SIGNING_TIME, OID_SM3, OID_SM3_WITH_SM2, } from './oids.js';
+import { attributeOctets, attributeOid, attributeTime, parseSignedData, } from './parse.js';
+/**
+ * SM2 空用户标识（OpenSSL CMS 默认）。
+ *
+ * The empty SM2 user identifier (the OpenSSL CMS default).
+ */
+const EMPTY_USER_ID = new Uint8Array(0);
+/**
+ * 验证 CMS SignedData。
+ *
+ * 结构完全无法解析时返回 `{ valid: false, signers: [{ errorCode: 'MALFORMED' }] }`，
+ * 而不是抛错；wasm 未预热等环境错误仍会抛出。
+ *
+ * Verifies a CMS SignedData.
+ *
+ * When the structure cannot be parsed at all it returns
+ * `{ valid: false, signers: [{ errorCode: 'MALFORMED' }] }` instead of throwing;
+ * environment errors such as an unloaded wasm module are still thrown.
+ */
+export function verifySignedData(cms, opts = {}) {
+    let parsed;
+    try {
+        parsed = parseSignedData(cms);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            signers: [
+                {
+                    valid: false,
+                    errorCode: 'MALFORMED',
+                    error: err instanceof Error ? err.message : String(err),
+                },
+            ],
+        };
+    }
+    const certificates = [
+        ...parsed.certificates,
+        ...(opts.certificates ?? []).map((cert) => resolveCertificate(cert)),
+    ];
+    const detachedData = opts.detachedData === undefined ? undefined : toDataBytes(opts.detachedData);
+    const signers = parsed.signerInfos.map((signer) => verifySigner(parsed, signer, certificates, detachedData, opts.userID));
+    return {
+        valid: signers.length > 0 && signers.every((signer) => signer.valid),
+        signers,
+    };
+}
+// 验证单个 SignerInfo。
+//
+// Verifies a single SignerInfo.
+function verifySigner(parsed, signer, certificates, detachedData, userID) {
+    if (signer.digestAlgorithm !== OID_SM3) {
+        return fail('UNSUPPORTED_ALGORITHM', `unsupported digest algorithm ${signer.digestAlgorithm}`);
+    }
+    if (signer.signatureAlgorithm !== OID_SM3_WITH_SM2) {
+        return fail('UNSUPPORTED_ALGORITHM', `unsupported signature algorithm ${signer.signatureAlgorithm}`);
+    }
+    const certificate = findCertificate(signer, certificates);
+    if (certificate === undefined) {
+        return fail('NO_CERTIFICATE', 'signer certificate is not embedded and was not provided');
+    }
+    if (!certificate.supported) {
+        return fail('UNSUPPORTED_ALGORITHM', 'signer certificate public key is not SM2');
+    }
+    const content = parsed.eContent ?? detachedData;
+    let signingInput;
+    let signingTime;
+    if (signer.signedAttrs !== undefined) {
+        if (content === undefined) {
+            return fail('MALFORMED', 'detached data is required but was not supplied');
+        }
+        const attributes = signer.signedAttrs.attributes;
+        const contentType = attributeOid(attributeByOid(attributes, OID_CMS_CONTENT_TYPE));
+        if (contentType !== parsed.eContentType) {
+            return fail('DIGEST_MISMATCH', `contentType attribute ${String(contentType)} does not match ${parsed.eContentType}`);
+        }
+        const expectedDigest = attributeOctets(attributeByOid(attributes, OID_CMS_MESSAGE_DIGEST));
+        if (expectedDigest === undefined) {
+            return fail('MALFORMED', 'missing messageDigest attribute');
+        }
+        const actualDigest = hexToBytes(sm3.hash(content), 'messageDigest');
+        if (!equalBytes(expectedDigest, actualDigest)) {
+            return fail('DIGEST_MISMATCH', 'messageDigest does not match the content');
+        }
+        signingInput = signer.signedAttrs.raw;
+        signingTime = attributeTime(attributeByOid(attributes, OID_CMS_SIGNING_TIME));
+    }
+    else {
+        if (content === undefined) {
+            return fail('MALFORMED', 'detached data is required but was not supplied');
+        }
+        signingInput = content;
+    }
+    let signature;
+    try {
+        signature = derSignatureToRaw(signer.signature);
+    }
+    catch {
+        return fail('SIGNATURE_INVALID', 'malformed DER signature');
+    }
+    const valid = verifyWithUserId(certificate.subjectPublicKey, signingInput, signature, userID);
+    if (!valid)
+        return fail('SIGNATURE_INVALID', 'SM2 signature verification failed');
+    return {
+        valid: true,
+        certificate,
+        ...(signingTime === undefined ? {} : { signingTime }),
+    };
+}
+// 使用指定 SM2 用户 ID 验签。
+//
+// Verifies with an explicit SM2 user ID.
+function verifyWithUserId(publicKey, message, signature, userID) {
+    if (userID !== undefined) {
+        return sm2.verifyWithID(publicKey, message, signature, userID);
+    }
+    // 先试 OpenSSL CMS 的空标识，再试 GM/T 默认标识。
+    //
+    // Try the empty OpenSSL-CMS identifier first, then the GM/T default identifier.
+    if (sm2.verifyWithID(publicKey, message, signature, EMPTY_USER_ID))
+        return true;
+    return sm2.verifyWithID(publicKey, message, signature, DEFAULT_SM2_USER_ID);
+}
+// 按签名者标识查找证书。
+//
+// Finds the signer certificate by identifier.
+function findCertificate(signer, certificates) {
+    const sid = signer.sid;
+    if (sid.type === 'issuerAndSerialNumber') {
+        return certificates.find((cert) => cert.serialNumber === sid.serialNumber && equalBytes(cert.issuer.raw, sid.issuerRaw));
+    }
+    return certificates.find((cert) => cert.subjectKeyIdentifier !== undefined &&
+        equalBytes(cert.subjectKeyIdentifier, sid.keyIdentifier));
+}
+// 按 OID 查找签名属性。
+//
+// Finds a signed attribute by OID.
+function attributeByOid(attributes, target) {
+    return attributes.find((attribute) => attribute.oid === target);
+}
+// 把 Certificate / PEM / DER 输入统一为 Certificate。
+//
+// Normalizes Certificate / PEM / DER input.
+function resolveCertificate(input) {
+    if (isCertificateLike(input))
+        return input;
+    try {
+        return parseCertificate(input);
+    }
+    catch (err) {
+        throw new CmsError('verifySignedData: invalid certificate', { cause: err });
+    }
+}
+// 判断值是否像 Certificate。
+//
+// Checks whether a value looks like a Certificate.
+function isCertificateLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !(value instanceof Uint8Array) &&
+        'tbsCertificate' in value &&
+        'subjectPublicKey' in value);
+}
+// 把 data 输入统一为字节。
+//
+// Normalizes data input to bytes.
+function toDataBytes(data) {
+    if (data instanceof Uint8Array)
+        return new Uint8Array(data);
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data);
+    throw new TypeError('verifySignedData: detachedData must be a string or Uint8Array');
+}
+// 常量时间比较两个字节数组。
+//
+// Compares two byte arrays in constant time.
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+    }
+    return diff === 0;
+}
+// 构造失败结果。
+//
+// Builds a failure result.
+function fail(code, message) {
+    return { valid: false, errorCode: code, error: message };
+}
+/**
+ * 供调试：签名者标识的十六进制表示。
+ *
+ * For debugging: the signer identifier as hex.
+ */
+export function signerIdentifierHex(signer) {
+    if (signer.sid.type === 'subjectKeyIdentifier') {
+        return bytesToHex(signer.sid.keyIdentifier);
+    }
+    return `${bytesToHex(signer.sid.issuerRaw)}#${signer.sid.serialNumber.toString(16)}`;
+}

package/dist/common/hybrid.d.ts

@@ -8,6 +8,19 @@
  *   避免“空输入静默成功”。
  *
  * IV 同样按 hex / Uint8Array 处理，未提供时由宿主 CSPRNG 生成 12 字节。
+ *
+ * Shared input conventions for hybrid encryption.
+ *
+ * The two hybrid modules (SM2 / SM9) apply **the same** string semantics to `message`:
+ * - `Uint8Array`: used as is (copied);
+ * - `string`: must be hex (a `0x` prefix is allowed); base64 / UTF-8 are no longer
+ *   guessed;
+ * - pass `new Uint8Array(0)` for an empty message — an empty string is rejected
+ *   outright by the existing `toBytes` contract, which avoids "empty input silently
+ *   succeeds".
+ *
+ * The IV is likewise hex / Uint8Array; when omitted, 12 bytes are generated from the
+ * host CSPRNG.
  */
 /**
  * 把 hybrid 的 message 归一化为字节。
@@ -15,11 +28,23 @@
  * @param input hex 字符串或字节数组。
  * @param label 错误信息里的字段名。
  * @throws TypeError 空字符串、奇数长度、非 hex 字符或类型不对。
+ *
+ * Normalize the hybrid `message` into bytes.
+ *
+ * @param input A hex string or a byte array.
+ * @param label Field name used in error messages.
+ * @throws TypeError The string is empty or of odd length, contains a non-hex character,
+ *   or the value has the wrong type.
  */
 export declare function toMessageBytes(input: string | Uint8Array, label?: string): Uint8Array;
 /**
  * 归一化 hybrid 的 IV：未提供则新生成 12 字节；提供则必须恰好 12 字节。
  *
  * @throws RangeError 长度不是 12。
+ *
+ * Normalize the hybrid IV: generate 12 fresh bytes when absent; when supplied it must
+ * be exactly 12 bytes.
+ *
+ * @throws RangeError The length is not 12.
  */
 export declare function resolveIv(iv: string | Uint8Array | undefined): Uint8Array;

package/dist/common/hybrid.js

@@ -8,6 +8,19 @@
  *   避免“空输入静默成功”。
  *
  * IV 同样按 hex / Uint8Array 处理，未提供时由宿主 CSPRNG 生成 12 字节。
+ *
+ * Shared input conventions for hybrid encryption.
+ *
+ * The two hybrid modules (SM2 / SM9) apply **the same** string semantics to `message`:
+ * - `Uint8Array`: used as is (copied);
+ * - `string`: must be hex (a `0x` prefix is allowed); base64 / UTF-8 are no longer
+ *   guessed;
+ * - pass `new Uint8Array(0)` for an empty message — an empty string is rejected
+ *   outright by the existing `toBytes` contract, which avoids "empty input silently
+ *   succeeds".
+ *
+ * The IV is likewise hex / Uint8Array; when omitted, 12 bytes are generated from the
+ * host CSPRNG.
  */
 import { hexToBytes } from '../runtime/convert.js';
 import { randomBytes } from '../runtime/random.js';
@@ -18,6 +31,13 @@ import { SEALED_IV_LEN } from './sealed.js';
  * @param input hex 字符串或字节数组。
  * @param label 错误信息里的字段名。
  * @throws TypeError 空字符串、奇数长度、非 hex 字符或类型不对。
+ *
+ * Normalize the hybrid `message` into bytes.
+ *
+ * @param input A hex string or a byte array.
+ * @param label Field name used in error messages.
+ * @throws TypeError The string is empty or of odd length, contains a non-hex character,
+ *   or the value has the wrong type.
  */
 export function toMessageBytes(input, label = 'message') {
     if (input instanceof Uint8Array)
@@ -34,6 +54,11 @@ export function toMessageBytes(input, label = 'message') {
  * 归一化 hybrid 的 IV：未提供则新生成 12 字节；提供则必须恰好 12 字节。
  *
  * @throws RangeError 长度不是 12。
+ *
+ * Normalize the hybrid IV: generate 12 fresh bytes when absent; when supplied it must
+ * be exactly 12 bytes.
+ *
+ * @throws RangeError The length is not 12.
  */
 export function resolveIv(iv) {
     const out = iv === undefined