sm-crypto-wasm 0.7.0 → 0.7.1

package/dist/esbuild-plugin.js

@@ -23,7 +23,9 @@
  *   platform: 'browser',
  *   format: 'esm',
  *   outdir: 'dist/assets',        // 产物 JS 落这里
+ *                                 // output JS goes here
  *   plugins: [smCryptoWasm()],    // → wasm 复制到 dist/<algo>/<algo>.wasm
+ *                                 // copies wasm to dist/<algo>/<algo>.wasm
  * });
  * ```
  *
@@ -31,19 +33,69 @@
  * 产物目录的上级。
  *
  * 只需用到部分算法时传 `algorithms` 少复制几个。
+ *
+ * esbuild plugin: place the `.wasm` assets **where the runtime can resolve them** in a
+ * browser bundle.
+ *
+ * ## Why it is needed
+ *
+ * The browser loader fetches wasm with `fetch(new URL('../<algo>/<algo>.wasm',
+ * import.meta.url))` (a form both Vite and Webpack 5 understand: they archive the asset
+ * and rewrite the URL). **esbuild does not** — neither `--outfile` nor `--outdir` moves
+ * the file that `new URL` points at (measured on 0.28.2). Result: the build succeeds and
+ * `fetch` 404s at runtime.
+ *
+ * After the build finishes this plugin copies `dist/<algo>/<algo>.wasm` to that relative
+ * location: the runtime URL is `../<algo>/<algo>.wasm` relative to **the emitted JS
+ * file**, so the target base directory is **the parent of the directory holding the
+ * emitted JS** (derived from esbuild's `outdir` / `outfile`).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { smCryptoWasm } from 'sm-crypto-wasm/esbuild-plugin';
+ *
+ * await esbuild.build({
+ *   entryPoints: ['src/main.ts'],
+ *   bundle: true,
+ *   platform: 'browser',
+ *   format: 'esm',
+ *   outdir: 'dist/assets',        // the emitted JS lands here
+ *   plugins: [smCryptoWasm()],    // → wasm is copied to dist/<algo>/<algo>.wasm
+ * });
+ * ```
+ *
+ * Pointing `outdir` at a subdirectory (e.g. `dist/assets`) is recommended so the wasm
+ * lands in `dist/<algo>/` instead of the parent of the output directory.
+ *
+ * Pass `algorithms` when only some algorithms are used, to copy fewer files.
  */
 import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-/** 支持的算法名（与加载器白名单一致）。 */
+/** 支持的算法名（与加载器白名单一致）。
+ *
+ * Supported algorithm names (in sync with the loader allow-list).
+ */
 const WASM_ALGOS = ['sm2', 'sm3', 'sm4', 'sm9', 'zuc'];
-/** 本包 `dist/` 的位置（编译后插件自身就在 `dist/` 下）。 */
+/** 本包 `dist/` 的位置（编译后插件自身就在 `dist/` 下）。
+ *
+ * Location of this package's `dist/` (once compiled, the plugin itself lives under
+ * `dist/`).
+ */
 const THIS_DIST_DIR = dirname(fileURLToPath(import.meta.url));
 /**
  * 推导 wasm 的目标基目录。
  *
  * 运行时相对**产物 JS 文件**解析 `../<algo>/<algo>.wasm`，所以目标是产物 JS 目录的上级。
  * esbuild 通常把入口产物放在 `outdir` 根（单入口时 `outbase` 就是入口所在目录）。
+ *
+ * Derive the base directory for the wasm output.
+ *
+ * At runtime `../<algo>/<algo>.wasm` is resolved relative to **the emitted JS file**, so
+ * the target is the parent of the emitted JS directory. esbuild usually puts the entry
+ * output at the root of `outdir` (with a single entry, `outbase` is the entry's own
+ * directory).
  */
 function resolveTargetBase(opts) {
     if (opts.outdir)
@@ -57,6 +109,11 @@ function resolveTargetBase(opts) {
  *
  * @param options 见 {@link SmCryptoWasmPluginOptions}。
  * @returns 可直接放进 `plugins` 数组的插件对象。
+ *
+ * Create the esbuild plugin: copy the wasm assets after a successful build.
+ *
+ * @param options See {@link SmCryptoWasmPluginOptions}.
+ * @returns A plugin object that can be placed directly in the `plugins` array.
  */
 export function smCryptoWasm(options = {}) {
     const algos = options.algorithms ?? WASM_ALGOS;
@@ -66,15 +123,23 @@ export function smCryptoWasm(options = {}) {
         setup(build) {
             build.onEnd((result) => {
                 // 构建失败时不产出资源，避免留下半套产物。
+                //
+                // Emit no assets when the build failed, so no half-written output is left behind.
                 if (result.errors.length > 0)
                     return;
                 const targetBase = options.outDir ?? resolveTargetBase(build.initialOptions);
+                // `write: false` 等场景：没有落盘位置
+                //
+                // Cases such as `write: false`: there is no location to write to.
                 if (targetBase === undefined)
-                    return; // `write: false` 等场景：没有落盘位置
+                    return;
                 for (const algo of algos) {
                     const from = join(sourceDir, algo, `${algo}.wasm`);
+                    // 只装了部分算法时静默跳过。
+                    //
+                    // Silently skip algorithms that were not installed.
                     if (!existsSync(from))
-                        continue; // 只装了部分算法时静默跳过
+                        continue;
                     const to = join(targetBase, algo, `${algo}.wasm`);
                     mkdirSync(dirname(to), { recursive: true });
                     copyFileSync(from, to);

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  * import { sm3, sm4, zuc, sm2 } from 'sm-crypto-wasm';
  *
  * await sm3.ensureLoaded();          // 首次用某算法前预热其 wasm
+ *                                    // preload that algorithm's wasm before first use
  * sm3.hash('hello');
  * ```
  *
@@ -15,6 +16,24 @@
  * `import { encryptECB } from 'sm-crypto-wasm/sm4'`。
  *
  * spec/plan 对应：plan Task 12；spec §5 产物结构、§6 API。
+ *
+ * sm-crypto-wasm aggregate entry point (facade).
+ *
+ * Usage:
+ * ```ts
+ * import { sm3, sm4, zuc, sm2 } from 'sm-crypto-wasm';
+ *
+ * await sm3.ensureLoaded();          // warm an algorithm's wasm before first use
+ * sm3.hash('hello');
+ * ```
+ *
+ * Design: every algorithm is its own namespace exposing `ensureLoaded()` plus its
+ * business functions. The wasm is split per algorithm and only the algorithm that
+ * is actually called gets loaded (see the memoization in
+ * `src/runtime/loadWasm.ts`). Sub-path imports are supported for further
+ * tree-shaking: `import { encryptECB } from 'sm-crypto-wasm/sm4'`.
+ *
+ * spec/plan: plan Task 12; spec §5 artifact layout, §6 API.
  */
 export * as cms from './cms/index.js';
 export { bytesToHex, fromBytes, hexToBytes, toBytes } from './runtime/convert.js';

package/dist/index.js

@@ -6,6 +6,7 @@
  * import { sm3, sm4, zuc, sm2 } from 'sm-crypto-wasm';
  *
  * await sm3.ensureLoaded();          // 首次用某算法前预热其 wasm
+ *                                    // preload that algorithm's wasm before first use
  * sm3.hash('hello');
  * ```
  *
@@ -15,10 +16,31 @@
  * `import { encryptECB } from 'sm-crypto-wasm/sm4'`。
  *
  * spec/plan 对应：plan Task 12；spec §5 产物结构、§6 API。
+ *
+ * sm-crypto-wasm aggregate entry point (facade).
+ *
+ * Usage:
+ * ```ts
+ * import { sm3, sm4, zuc, sm2 } from 'sm-crypto-wasm';
+ *
+ * await sm3.ensureLoaded();          // warm an algorithm's wasm before first use
+ * sm3.hash('hello');
+ * ```
+ *
+ * Design: every algorithm is its own namespace exposing `ensureLoaded()` plus its
+ * business functions. The wasm is split per algorithm and only the algorithm that
+ * is actually called gets loaded (see the memoization in
+ * `src/runtime/loadWasm.ts`). Sub-path imports are supported for further
+ * tree-shaking: `import { encryptECB } from 'sm-crypto-wasm/sm4'`.
+ *
+ * spec/plan: plan Task 12; spec §5 artifact layout, §6 API.
  */
 export * as cms from './cms/index.js';
 export { bytesToHex, fromBytes, hexToBytes, toBytes } from './runtime/convert.js';
 // 运行时工具（错误类型、编解码）也导出，便于调用方捕获本库错误。
+//
+// Runtime helpers (error types, codecs) are re-exported so callers can catch
+// this library's errors.
 export { CiphertextError, DecryptionError, InvalidCiphertextError, InvalidKeyError, InvalidPublicKeyError, isSmCryptoError, SmCryptoError, } from './runtime/errors.js';
 export { loadWasm, loadWasmSync } from './runtime/loadWasm.js';
 export * as sm2 from './sm2/index.js';

package/dist/pem/asn1.d.ts

@@ -10,6 +10,19 @@
  * - `encodeOid` / `decodeOid` / `asn1IntValue` → OID 与 INTEGER 解码
  *
  * spec/plan 对应：X.509/CMS plan 阶段 0「迁移」。
+ *
+ * Legacy ASN.1 entry point (compatibility layer).
+ *
+ * The implementation moved to `src/asn1/` (the shared DER/BER layer). This file only
+ * keeps the historical export names so that `src/pem/*` and the existing tests did not
+ * have to change:
+ *
+ * - `parseDer` → `src/asn1/decode.ts`
+ * - `encodeDer` → `encode` in `src/asn1/encode.ts`
+ * - `asn1Int` / `asn1Octets` / `asn1Oid` / `asn1Null` / `asn1Seq` → the matching builders
+ * - `encodeOid` / `decodeOid` / `asn1IntValue` → OID and INTEGER decoding
+ *
+ * spec/plan: X.509/CMS plan phase 0, "migration".
  */
 export { decodeOid, encode as encodeDer, encodeOid, integer as asn1Int, nullValue as asn1Null, octetString as asn1Octets, oid as asn1Oid, parseDer, readInteger as asn1IntValue, seq as asn1Seq, } from '../asn1/index.js';
 export { Asn1Error, type Asn1Node } from '../asn1/types.js';

package/dist/pem/asn1.js

@@ -10,6 +10,19 @@
  * - `encodeOid` / `decodeOid` / `asn1IntValue` → OID 与 INTEGER 解码
  *
  * spec/plan 对应：X.509/CMS plan 阶段 0「迁移」。
+ *
+ * Legacy ASN.1 entry point (compatibility layer).
+ *
+ * The implementation moved to `src/asn1/` (the shared DER/BER layer). This file only
+ * keeps the historical export names so that `src/pem/*` and the existing tests did not
+ * have to change:
+ *
+ * - `parseDer` → `src/asn1/decode.ts`
+ * - `encodeDer` → `encode` in `src/asn1/encode.ts`
+ * - `asn1Int` / `asn1Octets` / `asn1Oid` / `asn1Null` / `asn1Seq` → the matching builders
+ * - `encodeOid` / `decodeOid` / `asn1IntValue` → OID and INTEGER decoding
+ *
+ * spec/plan: X.509/CMS plan phase 0, "migration".
  */
 export { decodeOid, encode as encodeDer, encodeOid, integer as asn1Int, nullValue as asn1Null, octetString as asn1Octets, oid as asn1Oid, parseDer, readInteger as asn1IntValue, seq as asn1Seq, } from '../asn1/index.js';
 export { Asn1Error } from '../asn1/types.js';

package/dist/pem/index.d.ts

@@ -1,5 +1,7 @@
 /**
  * PEM 子模块 barrel。
+ *
+ * PEM submodule barrel.
  */
 export * from './asn1.js';
 export * from './pkcs8.js';

package/dist/pem/index.js

@@ -1,5 +1,7 @@
 /**
  * PEM 子模块 barrel。
+ *
+ * PEM submodule barrel.
  */
 export * from './asn1.js';
 export * from './pkcs8.js';

package/dist/pem/pkcs8.d.ts

@@ -9,27 +9,83 @@
  * - AlgorithmIdentifier ::= SEQUENCE { algorithm OID, parameters ANY DEFINED BY algorithm OPTIONAL }
  *
  * 本仓库只支持"parameters = NULL"这一类算法（SM2 / SM9 都符合）。
+ *
+ * PKCS#8 PrivateKeyInfo and SPKI SubjectPublicKeyInfo parsing/encoding.
+ *
+ * spec/plan: plan Task 4; spec §12.1 Q3.
+ *
+ * Types involved:
+ * - PrivateKeyInfo ::= SEQUENCE { version INTEGER, algorithm AlgorithmIdentifier,
+ *   privateKey OCTET STRING [, attributes ...] }
+ * - SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier,
+ *   subjectPublicKey BIT STRING }
+ * - AlgorithmIdentifier ::= SEQUENCE { algorithm OID, parameters ANY DEFINED BY
+ *   algorithm OPTIONAL }
+ *
+ * This repository only supports algorithms of the "parameters = NULL" kind (both SM2
+ * and SM9 qualify).
  */
 /**
  * PrivateKeyInfo 的最小化解析结果。
+ *
+ * The minimally parsed result of a PrivateKeyInfo.
  */
 export interface ParsedPrivateKey {
-    /** 算法 OID，如 `"1.2.156.10197.1.100"`（SM9）。 */
+    /**
+     * 算法 OID，如 `"1.2.156.10197.1.100"`（SM9）。
+     *
+     * Algorithm OID, e.g. `"1.2.156.10197.1.100"` (SM9).
+     */
     readonly algorithmOid: string;
-    /** 原始私钥字节（EC privateKey OCTET STRING 内容，含可选 public-key 拼接）。 */
+    /**
+     * 原始私钥字节（EC privateKey OCTET STRING 内容，含可选 public-key 拼接）。
+     *
+     * Raw private key bytes (the contents of the EC privateKey OCTET STRING, including an
+     * optional concatenated public key).
+     */
     readonly privateKey: Uint8Array;
 }
-/** 编码 PrivateKeyInfo PEM。 */
+/**
+ * 编码 PrivateKeyInfo PEM。
+ *
+ * Encodes a PrivateKeyInfo PEM.
+ */
 export declare function encodePkcs8PrivateKey(algorithmOid: string, privateKey: Uint8Array): string;
-/** 解析 PRIVATE KEY PEM。 */
+/**
+ * 解析 PRIVATE KEY PEM。
+ *
+ * Parses a PRIVATE KEY PEM.
+ */
 export declare function parsePkcs8PrivateKey(pem: string): ParsedPrivateKey;
-/** SPKI 解析结果。 */
+/**
+ * SPKI 解析结果。
+ *
+ * The parsed result of an SPKI.
+ */
 export interface ParsedPublicKey {
+    /**
+     * 算法 OID，如 `"1.2.156.10197.1.100"`（SM9）。
+     *
+     * Algorithm OID, e.g. `"1.2.156.10197.1.100"` (SM9).
+     */
     readonly algorithmOid: string;
-    /** 公钥 BIT STRING 内容。对 EC 类算法：未使用字节 0x00 + X || Y（66 字节）。 */
+    /**
+     * 公钥 BIT STRING 内容。对 EC 类算法：未使用字节 0x00 + X || Y（66 字节）。
+     *
+     * Contents of the public key BIT STRING. For EC-like algorithms: the unused-bits byte
+     * 0x00 followed by X || Y (66 bytes).
+     */
     readonly publicKey: Uint8Array;
 }
-/** 编码 SPKI PEM（算法 OID + 公钥 BIT STRING）。 */
+/**
+ * 编码 SPKI PEM（算法 OID + 公钥 BIT STRING）。
+ *
+ * Encodes an SPKI PEM (algorithm OID + public key BIT STRING).
+ */
 export declare function encodeSpkiPublicKey(algorithmOid: string, publicKey: Uint8Array): string;
-/** 解析 PUBLIC KEY PEM。 */
+/**
+ * 解析 PUBLIC KEY PEM。
+ *
+ * Parses a PUBLIC KEY PEM.
+ */
 export declare function parseSpkiPublicKey(pem: string): ParsedPublicKey;

package/dist/pem/pkcs8.js

@@ -9,11 +9,30 @@
  * - AlgorithmIdentifier ::= SEQUENCE { algorithm OID, parameters ANY DEFINED BY algorithm OPTIONAL }
  *
  * 本仓库只支持"parameters = NULL"这一类算法（SM2 / SM9 都符合）。
+ *
+ * PKCS#8 PrivateKeyInfo and SPKI SubjectPublicKeyInfo parsing/encoding.
+ *
+ * spec/plan: plan Task 4; spec §12.1 Q3.
+ *
+ * Types involved:
+ * - PrivateKeyInfo ::= SEQUENCE { version INTEGER, algorithm AlgorithmIdentifier,
+ *   privateKey OCTET STRING [, attributes ...] }
+ * - SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier,
+ *   subjectPublicKey BIT STRING }
+ * - AlgorithmIdentifier ::= SEQUENCE { algorithm OID, parameters ANY DEFINED BY
+ *   algorithm OPTIONAL }
+ *
+ * This repository only supports algorithms of the "parameters = NULL" kind (both SM2
+ * and SM9 qualify).
  */
 import { base64ToBytes, bytesToBase64 } from '../runtime/convert.js';
 import { InvalidKeyError } from '../runtime/errors.js';
 import { asn1Int, asn1Null, asn1Octets, asn1Oid, asn1Seq, parseDer } from './asn1.js';
-/** 编码 PrivateKeyInfo PEM。 */
+/**
+ * 编码 PrivateKeyInfo PEM。
+ *
+ * Encodes a PrivateKeyInfo PEM.
+ */
 export function encodePkcs8PrivateKey(algorithmOid, privateKey) {
     const seq = asn1Seq([
         asn1Int(0),
@@ -22,12 +41,19 @@ export function encodePkcs8PrivateKey(algorithmOid, privateKey) {
     ]);
     return derToPem(seq.raw, 'PRIVATE KEY');
 }
-/** 解析 PRIVATE KEY PEM。 */
+/**
+ * 解析 PRIVATE KEY PEM。
+ *
+ * Parses a PRIVATE KEY PEM.
+ */
 export function parsePkcs8PrivateKey(pem) {
     const seq = parseDer(pemToDer(pem));
     if (seq.tag !== 0x10) {
-        // SEQUENCE = 0x10 in low-tag form (constructed context-specific) but
-        // UNIVERSAL SEQUENCE is 0x30. asn1.ts 把 tag 数字按 UNIVERSAL 存。
+        // `src/asn1` 存的是 UNIVERSAL tag 编号（SEQUENCE = 16 = 0x10），不是首字节
+        // 0x30，因此这里按编号比较。
+        //
+        // `src/asn1` stores the UNIVERSAL tag number (SEQUENCE = 16 = 0x10) rather than
+        // the leading byte 0x30, so the comparison uses the number.
         throw new InvalidKeyError('parsePkcs8PrivateKey: top-level is not SEQUENCE');
     }
     if (!seq.children || seq.children.length < 3) {
@@ -55,9 +81,15 @@ export function parsePkcs8PrivateKey(pem) {
         privateKey: privateKeyOctets.value,
     };
 }
-/** 编码 SPKI PEM（算法 OID + 公钥 BIT STRING）。 */
+/**
+ * 编码 SPKI PEM（算法 OID + 公钥 BIT STRING）。
+ *
+ * Encodes an SPKI PEM (algorithm OID + public key BIT STRING).
+ */
 export function encodeSpkiPublicKey(algorithmOid, publicKey) {
     // BIT STRING：未使用位 = 0，前缀一字节 0x00。
+    //
+    // BIT STRING: zero unused bits, prefixed with a single 0x00 byte.
     const bitStringValue = new Uint8Array(publicKey.length + 1);
     bitStringValue.set(publicKey, 1);
     const seq = asn1Seq([
@@ -66,7 +98,11 @@ export function encodeSpkiPublicKey(algorithmOid, publicKey) {
     ]);
     return derToPem(seq.raw, 'PUBLIC KEY');
 }
-/** 解析 PUBLIC KEY PEM。 */
+/**
+ * 解析 PUBLIC KEY PEM。
+ *
+ * Parses a PUBLIC KEY PEM.
+ */
 export function parseSpkiPublicKey(pem) {
     const seq = parseDer(pemToDer(pem));
     if (seq.tag !== 0x10) {
@@ -88,6 +124,8 @@ export function parseSpkiPublicKey(pem) {
         throw new InvalidKeyError('parseSpkiPublicKey: missing BIT STRING');
     }
     // 去掉 BIT STRING 第一个字节的"未使用位"计数（我们固定为 0）。
+    //
+    // Strip the leading unused-bit count of the BIT STRING (always 0 in our encoding).
     const inner = bitString.value.subarray(1);
     return {
         algorithmOid: decodeOidFromNode(oidNode),
@@ -95,6 +133,11 @@ export function parseSpkiPublicKey(pem) {
     };
 }
 // ----------------- 内部 -----------------
+//
+// ----------------- Internals -----------------
+// 从 ASN.1 节点解码 OID。
+//
+// Decodes an OID from an ASN.1 node.
 function decodeOidFromNode(node) {
     if (node.tag !== 0x06)
         throw new InvalidKeyError('decodeOidFromNode: not OID');
@@ -115,6 +158,9 @@ function decodeOidFromNode(node) {
         throw new InvalidKeyError('decodeOid: truncated');
     return parts.join('.');
 }
+// PEM → DER。
+//
+// PEM to DER.
 function pemToDer(pem) {
     const lines = pem.split(/\r?\n/);
     const body = [];
@@ -138,6 +184,9 @@ function pemToDer(pem) {
     const b64 = body.join('');
     return base64ToBytes(b64);
 }
+// DER → PEM。
+//
+// DER to PEM.
 function derToPem(der, kind) {
     const b64 = bytesToBase64(der);
     const lines = [];
@@ -146,6 +195,9 @@ function derToPem(der, kind) {
     }
     return `-----BEGIN ${kind}-----\n${lines.join('\n')}\n-----END ${kind}-----\n`;
 }
+// 构造 BIT STRING 节点。
+//
+// Builds a BIT STRING node.
 function bitStringNode(value) {
     const lengthBytes = encodeLen(value.length);
     const raw = new Uint8Array(1 + lengthBytes.length + value.length);
@@ -165,6 +217,9 @@ function bitStringNode(value) {
         raw,
     };
 }
+// 编码 DER 长度。
+//
+// Encodes a DER length.
 function encodeLen(n) {
     if (n < 0x80)
         return new Uint8Array([n]);
@@ -179,3 +234,8 @@ function encodeLen(n) {
 // base64 编解码统一走 `../runtime/convert.js` 的跨运行时实现（Node 走 Buffer
 // 快路径、浏览器回落 btoa/atob）；本文件原先自带一份，其 Node 分支直接引用了
 // `Buffer`，在浏览器里会 ReferenceError。
+//
+// base64 encoding/decoding goes through the cross-runtime implementation in
+// `../runtime/convert.js` (a Buffer fast path on Node, a btoa/atob fallback in the
+// browser). This file used to carry its own copy whose Node branch referenced `Buffer`
+// directly, which raised a ReferenceError in the browser.

package/dist/pem/sm2.d.ts

@@ -24,10 +24,44 @@
  *
  * 编码函数接受/产出与解析一致的格式（私钥 PKCS#8、公钥 SPKI），供
  * 密钥生成与测试使用。
+ *
+ * SM2 key PEM encoding/decoding (PKCS#8 / SEC1 / SPKI).
+ *
+ * Unlike the generic parsing in `./pkcs8`, this layer knows the SM2 encodings:
+ * - Private keys:
+ *   - PKCS#8 `PrivateKeyInfo` (`-----BEGIN PRIVATE KEY-----`); its `privateKey` OCTET
+ *     STRING holds an RFC 5915 `ECPrivateKey`:
+ *     ```
+ *     ECPrivateKey ::= SEQUENCE {
+ *       version      INTEGER (1),
+ *       privateKey   OCTET STRING,        -- 32-byte d
+ *       parameters   [0] EXPLICIT OBJECT IDENTIFIER OPTIONAL,  -- sm2p256v1
+ *       publicKey    [1] EXPLICIT BIT STRING OPTIONAL
+ *     }
+ *     ```
+ *   - SEC1 `ECPrivateKey` (`-----BEGIN EC PRIVATE KEY-----`) is exactly that structure.
+ * - Public keys: SPKI `SubjectPublicKeyInfo` (`-----BEGIN PUBLIC KEY-----`) with
+ *   `algorithm = { id-ecPublicKey, sm2p256v1 }` and a 65-byte uncompressed point
+ *   `04 || X || Y` as `subjectPublicKey`.
+ *
+ * Algorithm identifiers / curve OIDs:
+ * - id-ecPublicKey = 1.2.840.10045.2.1
+ * - sm2p256v1      = 1.2.156.10197.1.301
+ *
+ * The encoders produce the same formats the parsers accept (PKCS#8 for private keys,
+ * SPKI for public keys) for key generation and tests.
+ */
+/**
+ * `id-ecPublicKey` OID。
+ *
+ * The `id-ecPublicKey` OID.
  */
-/** `id-ecPublicKey` OID。 */
 export declare const OID_ID_EC_PUBLIC_KEY = "1.2.840.10045.2.1";
-/** `sm2p256v1`（推荐曲线）OID。 */
+/**
+ * `sm2p256v1`（推荐曲线）OID。
+ *
+ * The `sm2p256v1` (recommended curve) OID.
+ */
 export declare const OID_SM2_CURVE = "1.2.156.10197.1.301";
 /**
  * 解析 SM2 私钥 PEM，返回 32 字节私钥 d。
@@ -35,24 +69,44 @@ export declare const OID_SM2_CURVE = "1.2.156.10197.1.301";
  * 支持 PKCS#8（`BEGIN PRIVATE KEY`）与 SEC1（`BEGIN EC PRIVATE KEY`）。
  *
  * @throws InvalidKeyError PEM/DER 结构非法、或曲线不是 SM2。
+ *
+ * Parses an SM2 private key PEM and returns the 32-byte private key d.
+ *
+ * Supports PKCS#8 (`BEGIN PRIVATE KEY`) and SEC1 (`BEGIN EC PRIVATE KEY`).
+ *
+ * @throws InvalidKeyError When the PEM/DER structure is invalid or the curve is not SM2.
  */
 export declare function parseSm2PrivateKeyPem(pem: string): Uint8Array;
 /**
  * 解析 SM2 私钥 DER（PKCS#8 或 SEC1），返回 32 字节私钥 d。
  *
  * WebCrypto 的 `importKey('pkcs8', ...)` 使用这个入口。
+ *
+ * Parses an SM2 private key DER (PKCS#8 or SEC1) and returns the 32-byte private key d.
+ *
+ * WebCrypto's `importKey('pkcs8', ...)` uses this entry point.
  */
 export declare function parseSm2PrivateKeyDer(der: Uint8Array): Uint8Array;
 /**
  * 解析 SM2 公钥 PEM，返回 65 字节未压缩点 `04 || X || Y`。
  *
  * @throws InvalidKeyError PEM/DER 结构非法、曲线不是 SM2、或点不是未压缩形式。
+ *
+ * Parses an SM2 public key PEM and returns the 65-byte uncompressed point
+ * `04 || X || Y`.
+ *
+ * @throws InvalidKeyError When the PEM/DER structure is invalid, the curve is not SM2,
+ *   or the point is not in uncompressed form.
  */
 export declare function parseSm2PublicKeyPem(pem: string): Uint8Array;
 /**
  * 解析 SM2 公钥 DER（SPKI），返回 65 字节未压缩点。
  *
  * WebCrypto 的 `importKey('spki', ...)` 使用这个入口。
+ *
+ * Parses an SM2 public key DER (SPKI) and returns the 65-byte uncompressed point.
+ *
+ * WebCrypto's `importKey('spki', ...)` uses this entry point.
  */
 export declare function parseSm2PublicKeyDer(der: Uint8Array): Uint8Array;
 /**
@@ -60,15 +114,33 @@ export declare function parseSm2PublicKeyDer(der: Uint8Array): Uint8Array;
  *
  * @param d 32 字节私钥（hex / Uint8Array）。
  * @param pub 可选公钥（64 或 65 字节）；给出则内嵌到 ECPrivateKey 的 `[1]`。
+ *
+ * Encodes an SM2 private key as PKCS#8 PEM (`BEGIN PRIVATE KEY`).
+ *
+ * @param d 32-byte private key (hex / Uint8Array).
+ * @param pub Optional public key (64 or 65 bytes); when given it is embedded into the
+ *   `[1]` field of the ECPrivateKey.
  */
 export declare function encodeSm2PrivateKeyPem(d: string | Uint8Array, pub?: string | Uint8Array): string;
-/** 编码 SM2 私钥为 PKCS#8 DER。 */
+/**
+ * 编码 SM2 私钥为 PKCS#8 DER。
+ *
+ * Encodes an SM2 private key as PKCS#8 DER.
+ */
 export declare function encodeSm2PrivateKeyDer(d: string | Uint8Array, pub?: string | Uint8Array): Uint8Array;
 /**
  * 编码 SM2 公钥为 SPKI PEM（`BEGIN PUBLIC KEY`）。
  *
  * @param pub 64（X || Y）或 65（04 || X || Y）字节公钥。
+ *
+ * Encodes an SM2 public key as SPKI PEM (`BEGIN PUBLIC KEY`).
+ *
+ * @param pub 64-byte (X || Y) or 65-byte (04 || X || Y) public key.
  */
 export declare function encodeSm2PublicKeyPem(pub: string | Uint8Array): string;
-/** 编码 SM2 公钥为 SPKI DER。 */
+/**
+ * 编码 SM2 公钥为 SPKI DER。
+ *
+ * Encodes an SM2 public key as SPKI DER.
+ */
 export declare function encodeSm2PublicKeyDer(pub: string | Uint8Array): Uint8Array;