sm-crypto-wasm 0.7.0 → 0.7.1

package/dist/asn1/encode.js

@@ -8,12 +8,29 @@
  * - BOOLEAN TRUE 编码为 0xFF；
  * - INTEGER 使用最小补码编码；
  * - 输出始终是 definite-length（BER indefinite 只在解析侧接受）。
+ *
+ * ASN.1 DER encoder and builders.
+ *
+ * Rules:
+ * - `encode()` rebuilds the leading byte from `cls + constructed + tag` (fixing the
+ *   legacy implementation dropping the constructed bit) and recurses into children
+ *   of constructed nodes;
+ * - SET OF is sorted by encoded bytes (a DER requirement);
+ * - BOOLEAN TRUE is encoded as 0xFF;
+ * - INTEGER uses minimal two's-complement encoding;
+ * - output is always definite-length (BER indefinite is only accepted when parsing).
  */
 import { encodeOid } from './oid.js';
 import { encodeGeneralizedTime, encodeTime, encodeUtcTime } from './time.js';
 import { Asn1Class, Asn1Error, UniversalTag } from './types.js';
 // ----------------- 基础编码 -----------------
-/** 编码单个节点为 DER 字节。 */
+//
+// ----------------- Basic encoding -----------------
+/**
+ * 编码单个节点为 DER 字节。
+ *
+ * Encodes a single node to DER bytes.
+ */
 export function encode(node) {
     const constructed = node.children !== undefined ? true : node.constructed;
     const value = constructed
@@ -28,9 +45,17 @@ export function encode(node) {
  * `encode` 的旧名（兼容 `src/pem/asn1.ts` 的历史导出）。
  *
  * @deprecated 使用 `encode`。
+ *
+ * Legacy alias of `encode` (kept for the historical exports of `src/pem/asn1.ts`).
+ *
+ * @deprecated Use `encode`.
  */
 export const encodeDer = encode;
-/** 编码 tag 首字节（含高 tag number 的 base128 展开）。 */
+/**
+ * 编码 tag 首字节（含高 tag number 的 base128 展开）。
+ *
+ * Encodes the tag's leading byte (including base128 expansion of high tag numbers).
+ */
 export function encodeTag(cls, constructed, tag) {
     if (!Number.isInteger(tag) || tag < 0) {
         throw new Asn1Error(`encodeTag: invalid tag ${tag}`);
@@ -50,7 +75,11 @@ export function encodeTag(cls, constructed, tag) {
     out.push(...groups);
     return new Uint8Array(out);
 }
-/** 编码 definite-length。 */
+/**
+ * 编码 definite-length。
+ *
+ * Encodes a definite length.
+ */
 export function encodeLength(length) {
     if (!Number.isInteger(length) || length < 0) {
         throw new Asn1Error(`encodeLength: bad length ${length}`);
@@ -66,15 +95,29 @@ export function encodeLength(length) {
     return new Uint8Array([0x80 | bytes.length, ...bytes]);
 }
 // ----------------- 构造器 -----------------
-/** 构造 SEQUENCE。 */
+//
+// ----------------- Builders -----------------
+/**
+ * 构造 SEQUENCE。
+ *
+ * Builds a SEQUENCE.
+ */
 export function seq(children) {
     return makeConstructed(Asn1Class.Universal, UniversalTag.Sequence, children);
 }
-/** 构造 SET（保持给定顺序；ASN.1 SET 的排序语义由调用方负责）。 */
+/**
+ * 构造 SET（保持给定顺序；ASN.1 SET 的排序语义由调用方负责）。
+ *
+ * Builds a SET, keeping the given order; ordering semantics are the caller's job.
+ */
 export function set(children) {
     return makeConstructed(Asn1Class.Universal, UniversalTag.Set, children);
 }
-/** 构造 SET OF（按 DER 编码字节排序）。 */
+/**
+ * 构造 SET OF（按 DER 编码字节排序）。
+ *
+ * Builds a SET OF, sorted by encoded DER bytes.
+ */
 export function setOf(children) {
     const sorted = children
         .map((node) => ({ node, bytes: encode(node) }))
@@ -82,7 +125,11 @@ export function setOf(children) {
         .map((entry) => entry.node);
     return makeConstructed(Asn1Class.Universal, UniversalTag.Set, sorted);
 }
-/** 构造 `[tag] EXPLICIT` 包装。 */
+/**
+ * 构造 `[tag] EXPLICIT` 包装。
+ *
+ * Builds a `[tag] EXPLICIT` wrapper.
+ */
 export function explicit(tag, inner) {
     const value = encode(inner);
     return {
@@ -102,6 +149,9 @@ export function explicit(tag, inner) {
 }
 /**
  * 构造 `[tag] IMPLICIT` 包装：只替换外层标签，内容保持不变。
+ *
+ * Builds a `[tag] IMPLICIT` wrapper: only the outer tag is replaced, the content is
+ * kept unchanged.
  */
 export function implicit(tag, inner, cls = Asn1Class.ContextSpecific) {
     const constructed = inner.children !== undefined ? true : inner.constructed;
@@ -117,7 +167,11 @@ export function implicit(tag, inner, cls = Asn1Class.ContextSpecific) {
         raw: concat([encodeTag(cls, constructed, tag), encodeLength(value.length), value]),
     };
 }
-/** 构造 BIT STRING。`unusedBits` 为末尾未使用位数（0..7）。 */
+/**
+ * 构造 BIT STRING。`unusedBits` 为末尾未使用位数（0..7）。
+ *
+ * Builds a BIT STRING; `unusedBits` is the number of unused trailing bits (0..7).
+ */
 export function bitString(bytes, unusedBits = 0) {
     if (!Number.isInteger(unusedBits) || unusedBits < 0 || unusedBits > 7) {
         throw new RangeError(`bitString: unusedBits must be 0..7, got ${unusedBits}`);
@@ -127,41 +181,73 @@ export function bitString(bytes, unusedBits = 0) {
     value.set(bytes, 1);
     return makePrimitive(UniversalTag.BitString, value);
 }
-/** 构造 OCTET STRING。 */
+/**
+ * 构造 OCTET STRING。
+ *
+ * Builds an OCTET STRING.
+ */
 export function octetString(bytes) {
     return makePrimitive(UniversalTag.OctetString, bytes);
 }
-/** 构造 BOOLEAN。 */
+/**
+ * 构造 BOOLEAN。
+ *
+ * Builds a BOOLEAN.
+ */
 export function boolean(value) {
     return makePrimitive(UniversalTag.Boolean, new Uint8Array([value ? 0xff : 0x00]));
 }
-/** 构造 NULL。 */
+/**
+ * 构造 NULL。
+ *
+ * Builds a NULL.
+ */
 export function nullValue() {
     return makePrimitive(UniversalTag.Null, new Uint8Array(0));
 }
-/** 构造 INTEGER（最小补码编码）。 */
+/**
+ * 构造 INTEGER（最小补码编码）。
+ *
+ * Builds an INTEGER (minimal two's-complement encoding).
+ */
 export function integer(value) {
     const v = typeof value === 'number' ? BigInt(value) : value;
     if (typeof v !== 'bigint')
         throw new Asn1Error('integer: value must be bigint or number');
     return makePrimitive(UniversalTag.Integer, encodeIntegerValue(v));
 }
-/** 构造 OBJECT IDENTIFIER。 */
+/**
+ * 构造 OBJECT IDENTIFIER。
+ *
+ * Builds an OBJECT IDENTIFIER.
+ */
 export function oid(value) {
     return makePrimitive(UniversalTag.ObjectIdentifier, encodeOid(value));
 }
-/** 构造 UTF8String。 */
+/**
+ * 构造 UTF8String。
+ *
+ * Builds a UTF8String.
+ */
 export function utf8String(value) {
     return makePrimitive(UniversalTag.Utf8String, new TextEncoder().encode(value));
 }
-/** 构造 PrintableString（仅允许 A-Z a-z 0-9 与 `'()+,-./:=?` 和空格）。 */
+/**
+ * 构造 PrintableString（仅允许 A-Z a-z 0-9 与 `'()+,-./:=?` 和空格）。
+ *
+ * Builds a PrintableString (only A-Z a-z 0-9 and `'()+,-./:=?` plus space allowed).
+ */
 export function printableString(value) {
     if (!/^[A-Za-z0-9 '()+,\-./:=?]*$/.test(value)) {
         throw new Asn1Error(`printableString: unsupported character in "${value}"`);
     }
     return makePrimitive(UniversalTag.PrintableString, asciiBytes(value));
 }
-/** 构造 IA5String（仅 ASCII）。 */
+/**
+ * 构造 IA5String（仅 ASCII）。
+ *
+ * Builds an IA5String (ASCII only).
+ */
 export function ia5String(value) {
     for (let i = 0; i < value.length; i++) {
         if (value.charCodeAt(i) > 0x7f) {
@@ -170,19 +256,38 @@ export function ia5String(value) {
     }
     return makePrimitive(UniversalTag.Ia5String, asciiBytes(value));
 }
-/** 构造 UTCTime（1950–2049）。 */
+/**
+ * 构造 UTCTime（1950–2049）。
+ *
+ * Builds a UTCTime (years 1950–2049).
+ */
 export function utcTime(date) {
     return makePrimitive(UniversalTag.UtcTime, asciiBytes(encodeUtcTime(date)));
 }
-/** 构造 GeneralizedTime。 */
+/**
+ * 构造 GeneralizedTime。
+ *
+ * Builds a GeneralizedTime.
+ */
 export function generalizedTime(date) {
     return makePrimitive(UniversalTag.GeneralizedTime, asciiBytes(encodeGeneralizedTime(date)));
 }
-/** 按 RFC 5280 自动选择 UTCTime / GeneralizedTime。 */
+/**
+ * 按 RFC 5280 自动选择 UTCTime / GeneralizedTime。
+ *
+ * Picks UTCTime / GeneralizedTime automatically as RFC 5280 requires.
+ */
 export function time(date) {
     return makePrimitive(isUtcYear(date) ? UniversalTag.UtcTime : UniversalTag.GeneralizedTime, asciiBytes(encodeTime(date)));
 }
 // ----------------- 内部 -----------------
+//
+// ----------------- Internals -----------------
+/**
+ * 构造 UNIVERSAL primitive 节点。
+ *
+ * Builds a UNIVERSAL primitive node.
+ */
 function makePrimitive(tag, value) {
     return {
         cls: Asn1Class.Universal,
@@ -194,6 +299,12 @@ function makePrimitive(tag, value) {
         raw: concat([encodeTag(Asn1Class.Universal, false, tag), encodeLength(value.length), value]),
     };
 }
+/**
+ * 构造 UNIVERSAL constructed 节点（value 由子节点编码拼接而成）。
+ *
+ * Builds a UNIVERSAL constructed node whose value is the concatenated encoded
+ * children.
+ */
 function makeConstructed(cls, tag, children) {
     const value = concat(children.map((child) => encode(child)));
     return {
@@ -207,6 +318,11 @@ function makeConstructed(cls, tag, children) {
         raw: concat([encodeTag(cls, true, tag), encodeLength(value.length), value]),
     };
 }
+/**
+ * 判断日期年份是否落在 UTCTime 适用范围（1950–2049）。
+ *
+ * Whether the year falls in the UTCTime range (1950–2049).
+ */
 function isUtcYear(date) {
     if (!(date instanceof Date) || Number.isNaN(date.getTime()))
         return false;
@@ -219,6 +335,13 @@ function isUtcYear(date) {
  * - 0 → `00`；
  * - 正数：最高位为 1 时前置 `00`；
  * - 负数：选择最少字节数 n 使 `-2^(8n-1) <= v`，按 2^(8n) 取模。
+ *
+ * Minimal two's-complement INTEGER encoding.
+ *
+ * - 0 → `00`;
+ * - positive: prepend `00` when the top bit would otherwise be set;
+ * - negative: pick the fewest bytes n such that `-2^(8n-1) <= v`, then reduce modulo
+ *   2^(8n).
  */
 export function encodeIntegerValue(v) {
     if (v === 0n)
@@ -246,12 +369,23 @@ export function encodeIntegerValue(v) {
     }
     return out;
 }
+/**
+ * 字符串 → ASCII 字节（高于 0x7f 的码位被截断，调用方负责预先校验）。
+ *
+ * String to ASCII bytes; code points above 0x7f are truncated, so callers must
+ * validate beforehand.
+ */
 function asciiBytes(text) {
     const out = new Uint8Array(text.length);
     for (let i = 0; i < text.length; i++)
         out[i] = text.charCodeAt(i) & 0x7f;
     return out;
 }
+/**
+ * 字节字典序比较（DER SET OF 排序依据）。
+ *
+ * Lexicographic byte comparison, the ordering rule for DER SET OF.
+ */
 function compareBytes(a, b) {
     const n = Math.min(a.length, b.length);
     for (let i = 0; i < n; i++) {
@@ -261,6 +395,11 @@ function compareBytes(a, b) {
     }
     return a.length - b.length;
 }
+/**
+ * 拼多个字节数组为一个新数组。
+ *
+ * Concatenates byte arrays into a new array.
+ */
 function concat(parts) {
     let total = 0;
     for (const p of parts)

package/dist/asn1/index.d.ts

@@ -3,6 +3,12 @@
  *
  * **不进入主入口导出**（spec Anti-Goal：不公开底层 DER/大数接口）。
  * `src/pem/asn1.ts` 仍按旧符号名 re-export 本层，供 PEM/PKCS#8 代码与测试使用。
+ *
+ * Internal ASN.1 layer barrel.
+ *
+ * **Not exported from the main entry** (spec anti-goal: the low-level DER/big-number
+ * interfaces stay private). `src/pem/asn1.ts` still re-exports this layer under the
+ * legacy symbol names for the PEM/PKCS#8 code and the tests.
  */
 export * from './decode.js';
 export * from './encode.js';

package/dist/asn1/index.js

@@ -3,6 +3,12 @@
  *
  * **不进入主入口导出**（spec Anti-Goal：不公开底层 DER/大数接口）。
  * `src/pem/asn1.ts` 仍按旧符号名 re-export 本层，供 PEM/PKCS#8 代码与测试使用。
+ *
+ * Internal ASN.1 layer barrel.
+ *
+ * **Not exported from the main entry** (spec anti-goal: the low-level DER/big-number
+ * interfaces stay private). `src/pem/asn1.ts` still re-exports this layer under the
+ * legacy symbol names for the PEM/PKCS#8 code and the tests.
  */
 export * from './decode.js';
 export * from './encode.js';

package/dist/asn1/oid.d.ts

@@ -6,17 +6,35 @@
  *   长组件不会溢出）；
  * - 首个子标识符也走 base128 编码，支持 `2.999` 这类第二组件 ≥ 40 的 OID；
  * - 解码时拒绝截断、空输入与非最小（前导 0x80）编码。
+ *
+ * OBJECT IDENTIFIER encoding and decoding.
+ *
+ * Differences from the legacy implementation:
+ * - Accumulates in `bigint`, so 32-bit bitwise limits no longer apply (long arcs such
+ *   as `1.2.840.113549...` cannot overflow);
+ * - The first subidentifier also goes through base128, so OIDs whose second arc is
+ *   ≥ 40 (such as `2.999`) are supported;
+ * - Decoding rejects truncation, empty input and non-minimal (leading 0x80) encodings.
  */
 /**
  * 点分 OID → 内容字节（不含 tag 与 length）。
  *
  * @param oid 形如 `"1.2.156.10197.1.100"`。
  * @throws Asn1Error 格式非法或组件越界。
+ *
+ * Dotted OID → content bytes (without tag and length).
+ *
+ * @param oid Something like `"1.2.156.10197.1.100"`.
+ * @throws Asn1Error On malformed syntax or out-of-range components.
  */
 export declare function encodeOid(oid: string): Uint8Array;
 /**
  * 内容字节 → 点分 OID。
  *
  * @throws Asn1Error 空输入、截断或非法 base128 编码。
+ *
+ * Content bytes → dotted OID.
+ *
+ * @throws Asn1Error On empty input, truncation, or an invalid base128 encoding.
  */
 export declare function decodeOid(bytes: Uint8Array): string;

package/dist/asn1/oid.js

@@ -6,6 +6,15 @@
  *   长组件不会溢出）；
  * - 首个子标识符也走 base128 编码，支持 `2.999` 这类第二组件 ≥ 40 的 OID；
  * - 解码时拒绝截断、空输入与非最小（前导 0x80）编码。
+ *
+ * OBJECT IDENTIFIER encoding and decoding.
+ *
+ * Differences from the legacy implementation:
+ * - Accumulates in `bigint`, so 32-bit bitwise limits no longer apply (long arcs such
+ *   as `1.2.840.113549...` cannot overflow);
+ * - The first subidentifier also goes through base128, so OIDs whose second arc is
+ *   ≥ 40 (such as `2.999`) are supported;
+ * - Decoding rejects truncation, empty input and non-minimal (leading 0x80) encodings.
  */
 import { Asn1Error } from './types.js';
 /**
@@ -13,6 +22,11 @@ import { Asn1Error } from './types.js';
  *
  * @param oid 形如 `"1.2.156.10197.1.100"`。
  * @throws Asn1Error 格式非法或组件越界。
+ *
+ * Dotted OID → content bytes (without tag and length).
+ *
+ * @param oid Something like `"1.2.156.10197.1.100"`.
+ * @throws Asn1Error On malformed syntax or out-of-range components.
  */
 export function encodeOid(oid) {
     const parts = parseOidComponents(oid);
@@ -27,6 +41,10 @@ export function encodeOid(oid) {
  * 内容字节 → 点分 OID。
  *
  * @throws Asn1Error 空输入、截断或非法 base128 编码。
+ *
+ * Content bytes → dotted OID.
+ *
+ * @throws Asn1Error On empty input, truncation, or an invalid base128 encoding.
  */
 export function decodeOid(bytes) {
     if (bytes.length === 0)
@@ -37,6 +55,8 @@ export function decodeOid(bytes) {
     for (let i = 0; i < bytes.length; i++) {
         const octet = bytes[i] ?? 0;
         // 每个子标识符的编码不得以 0x80 开头（非最小编码）。
+        //
+        // A subidentifier's encoding must not start with 0x80 (non-minimal encoding).
         if (!pending && octet === 0x80) {
             throw new Asn1Error('decodeOid: non-minimal base128 encoding');
         }
@@ -67,6 +87,11 @@ export function decodeOid(bytes) {
     const parts = [a, b, ...values.slice(1)];
     return parts.map((v) => v.toString(10)).join('.');
 }
+/**
+ * 校验并拆分点分 OID（每个组件为无符号十进制整数）。
+ *
+ * Validates and splits a dotted OID (each component is an unsigned decimal integer).
+ */
 function parseOidComponents(oid) {
     if (typeof oid !== 'string' || oid.length === 0) {
         throw new Asn1Error(`encodeOid: bad oid "${String(oid)}"`);
@@ -90,7 +115,11 @@ function parseOidComponents(oid) {
     }
     return parts;
 }
-/** 无符号 bigint → base128 字节（高位 bit 为续行标志）。 */
+/**
+ * 无符号 bigint → base128 字节（高位 bit 为续行标志）。
+ *
+ * Unsigned bigint → base128 bytes (the high bit marks a continuation).
+ */
 function encodeBase128(value) {
     if (value < 0n)
         throw new Asn1Error(`encodeBase128: negative value ${value}`);

package/dist/asn1/time.d.ts

@@ -8,21 +8,43 @@
  *
  * 解析刻意宽松（接受无秒、无时区、GeneralizedTime 的小数秒），因为真实现场
  * 存在非规范编码；编码始终输出规范形式。
+ *
+ * X.509 time encoding/parsing (UTCTime / GeneralizedTime).
+ *
+ * Rules (RFC 5280):
+ * - 1950–2049 use UTCTime (`YYMMDDHHMMSSZ`);
+ * - Other years use GeneralizedTime (`YYYYMMDDHHMMSSZ`);
+ * - Certificate time has second precision: milliseconds are truncated when parsing,
+ *   keeping parse → encode round-trips stable.
+ *
+ * Parsing is deliberately lenient (missing seconds, missing timezone, GeneralizedTime
+ * fractional seconds) because non-canonical encodings exist in the wild; encoding
+ * always emits the canonical form.
  */
 /**
  * 编码 UTCTime（仅接受 1950–2049 年）。
  *
  * @throws RangeError 日期无效或年份越界。
+ *
+ * Encodes a UTCTime (years 1950–2049 only).
+ *
+ * @throws RangeError When the Date is invalid or the year is out of range.
  */
 export declare function encodeUtcTime(date: Date): string;
 /**
  * 编码 GeneralizedTime。
  *
  * @throws RangeError 日期无效。
+ *
+ * Encodes a GeneralizedTime.
+ *
+ * @throws RangeError When the Date is invalid.
  */
 export declare function encodeGeneralizedTime(date: Date): string;
 /**
  * 按 RFC 5280 自动选择 UTCTime（1950–2049）或 GeneralizedTime。
+ *
+ * Picks UTCTime (1950–2049) or GeneralizedTime automatically as RFC 5280 requires.
  */
 export declare function encodeTime(date: Date): string;
 /**
@@ -35,5 +57,15 @@ export declare function encodeTime(date: Date): string;
  *
  * @returns 毫秒为 0 的 `Date`。
  * @throws Asn1Error 格式或日期分量非法。
+ *
+ * Parses a UTCTime or GeneralizedTime string.
+ *
+ * Accepts:
+ * - `YYMMDDHHMMSSZ` / `YYMMDDHHMMZ` (UTCTime; 50–99 → 1950–1999, 00–49 → 2000–2049);
+ * - `YYYYMMDDHHMMSSZ` / `YYYYMMDDHHMMZ` / `YYYYMMDDHHMMSS.sssZ` (GeneralizedTime);
+ * - an optional `+HHMM` / `-HHMM` offset on the time part; a missing timezone means UTC.
+ *
+ * @returns A `Date` whose milliseconds are 0.
+ * @throws Asn1Error On illegal syntax or date components.
  */
 export declare function parseTime(text: string): Date;

package/dist/asn1/time.js

@@ -8,12 +8,28 @@
  *
  * 解析刻意宽松（接受无秒、无时区、GeneralizedTime 的小数秒），因为真实现场
  * 存在非规范编码；编码始终输出规范形式。
+ *
+ * X.509 time encoding/parsing (UTCTime / GeneralizedTime).
+ *
+ * Rules (RFC 5280):
+ * - 1950–2049 use UTCTime (`YYMMDDHHMMSSZ`);
+ * - Other years use GeneralizedTime (`YYYYMMDDHHMMSSZ`);
+ * - Certificate time has second precision: milliseconds are truncated when parsing,
+ *   keeping parse → encode round-trips stable.
+ *
+ * Parsing is deliberately lenient (missing seconds, missing timezone, GeneralizedTime
+ * fractional seconds) because non-canonical encodings exist in the wild; encoding
+ * always emits the canonical form.
  */
 import { Asn1Error } from './types.js';
 /**
  * 编码 UTCTime（仅接受 1950–2049 年）。
  *
  * @throws RangeError 日期无效或年份越界。
+ *
+ * Encodes a UTCTime (years 1950–2049 only).
+ *
+ * @throws RangeError When the Date is invalid or the year is out of range.
  */
 export function encodeUtcTime(date) {
     const { year, month, day, hour, minute, second } = utcParts(date, 'encodeUtcTime');
@@ -27,6 +43,10 @@ export function encodeUtcTime(date) {
  * 编码 GeneralizedTime。
  *
  * @throws RangeError 日期无效。
+ *
+ * Encodes a GeneralizedTime.
+ *
+ * @throws RangeError When the Date is invalid.
  */
 export function encodeGeneralizedTime(date) {
     const { year, month, day, hour, minute, second } = utcParts(date, 'encodeGeneralizedTime');
@@ -34,6 +54,8 @@ export function encodeGeneralizedTime(date) {
 }
 /**
  * 按 RFC 5280 自动选择 UTCTime（1950–2049）或 GeneralizedTime。
+ *
+ * Picks UTCTime (1950–2049) or GeneralizedTime automatically as RFC 5280 requires.
  */
 export function encodeTime(date) {
     const year = utcParts(date, 'encodeTime').year;
@@ -49,6 +71,16 @@ export function encodeTime(date) {
  *
  * @returns 毫秒为 0 的 `Date`。
  * @throws Asn1Error 格式或日期分量非法。
+ *
+ * Parses a UTCTime or GeneralizedTime string.
+ *
+ * Accepts:
+ * - `YYMMDDHHMMSSZ` / `YYMMDDHHMMZ` (UTCTime; 50–99 → 1950–1999, 00–49 → 2000–2049);
+ * - `YYYYMMDDHHMMSSZ` / `YYYYMMDDHHMMZ` / `YYYYMMDDHHMMSS.sssZ` (GeneralizedTime);
+ * - an optional `+HHMM` / `-HHMM` offset on the time part; a missing timezone means UTC.
+ *
+ * @returns A `Date` whose milliseconds are 0.
+ * @throws Asn1Error On illegal syntax or date components.
  */
 export function parseTime(text) {
     const s = text.trim();
@@ -74,6 +106,9 @@ export function parseTime(text) {
     }
     const localMs = Date.UTC(year, month - 1, day, hour, minute, second);
     // 先在「输入的本地分量」上校验日期合法性，再应用时区偏移。
+    //
+    // Validate the date against the input's local components first, then apply the
+    // timezone offset.
     const local = new Date(localMs);
     if (Number.isNaN(local.getTime()) ||
         local.getUTCFullYear() !== year ||
@@ -86,10 +121,19 @@ export function parseTime(text) {
     }
     return new Date(localMs - offsetMinutes * 60_000);
 }
-/** UTCTime 两位年份展开。 */
+/**
+ * UTCTime 两位年份展开。
+ *
+ * Expands a two-digit UTCTime year.
+ */
 function utcYear(yy) {
     return yy >= 50 ? 1900 + yy : 2000 + yy;
 }
+/**
+ * 提取日期的 UTC 分量并校验日期有效性。
+ *
+ * Extracts the UTC components of a Date and validates it.
+ */
 function utcParts(date, where) {
     if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
         throw new RangeError(`${where}: invalid Date`);
@@ -103,9 +147,19 @@ function utcParts(date, where) {
         second: date.getUTCSeconds(),
     };
 }
+/**
+ * 十进制补零到 2 位。
+ *
+ * Zero-pads a decimal number to 2 digits.
+ */
 function pad2(n) {
     return n.toString(10).padStart(2, '0');
 }
+/**
+ * 十进制补零到 4 位。
+ *
+ * Zero-pads a decimal number to 4 digits.
+ */
 function pad4(n) {
     return n.toString(10).padStart(4, '0');
 }