sm-crypto-wasm 0.3.1 → 0.7.0

package/README.md

@@ -205,11 +205,32 @@ zuc.zucMac(key, macIv, '616263');               // → 4 字节标签
 
 ---
 
+### X.509 · CMS · WebCrypto
+
+```ts
+import { x509, cms, webcrypto } from 'sm-crypto-wasm';
+
+const cert = x509.parseCertificate(pem);
+const signed = cms.signData({ data, privateKey, certificate: cert });
+const digest = await webcrypto.subtle.digest('SM3', data);
+```
+
+- **X.509**：证书解析、单证书验签、自签 / 简单 CA 签发（[文档](https://jktantan.github.io/sm-crypto-wasm/guide/x509)）；
+- **CMS**：SignedData detached / attached、`signedAttrs` 原始 DER 验签、BER（[文档](https://jktantan.github.io/sm-crypto-wasm/guide/cms)）；
+- **WebCrypto**：`subtle` 风格的 SM3 / HMAC(SM3) / SM2 / SM4 子集（[文档](https://jktantan.github.io/sm-crypto-wasm/guide/webcrypto)）。
+
+X.509 / CMS 不做证书链路径校验、CRL/OCSP；WebCrypto 不是原生 `crypto.subtle` 的 polyfill。
+
+---
+
 ## API 一览
 
 | 模块 | 函数 |
 |---|---|
-| `sm2` | `generateKeyPair`(async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator`(async) · `createExchangeResponder`(async) |
+| `sm2` | `generateKeyPair`(async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `preparePublicKey`(async) · `configurePreparedKeyCache` · `clearPreparedPublicKeys` · `getPreparedPublicKeys` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator`(async) · `createExchangeResponder`(async) |
+| `webcrypto` | `subtle` · `CryptoKey` |
+| `cms` | `signData` · `verifySignedData` · `parseSignedData` · `CmsError` |
+| `x509` | `parseCertificate` · `parseCertificates` · `createSelfSignedCertificate` · `issueCertificate` · `parseDistinguishedName` · `verifyCertificateSignature` |
 | `sm3` | `hash` · `hmac` |
 | `sm4` | `encryptECB`/`decryptECB` · `encryptCBC`/`decryptCBC` · `encryptCTR`/`decryptCTR` · `encryptCFB`/`decryptCFB` · `encryptOFB`/`decryptOFB` · `encryptGCM`/`decryptGCM` |
 | `sm9` | `generateKeyPair`(async) · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator`(async) · `createExchangeResponder`(async) |
@@ -228,7 +249,7 @@ import { hash } from 'sm-crypto-wasm/sm3';
 import { encryptCBC } from 'sm-crypto-wasm/sm4';
 ```
 
-可用子路径：`sm-crypto-wasm/sm2` · `/sm3` · `/sm4` · `/sm9` · `/zuc`。
+可用子路径：`sm-crypto-wasm/sm2` · `/sm3` · `/sm4` · `/sm9` · `/x509` · `/cms` · `/webcrypto` · `/zuc`。
 
 ---
 
@@ -566,11 +587,32 @@ zuc.zucMac(key, macIv, '616263');               // → 4-byte tag
 
 ---
 
+### X.509 · CMS · WebCrypto
+
+```ts
+import { x509, cms, webcrypto } from 'sm-crypto-wasm';
+
+const cert = x509.parseCertificate(pem);
+const signed = cms.signData({ data, privateKey, certificate: cert });
+const digest = await webcrypto.subtle.digest('SM3', data);
+```
+
+- **X.509** — parsing, single-certificate verification, self-signed / simple CA issuing ([docs](https://jktantan.github.io/sm-crypto-wasm/en/guide/x509));
+- **CMS** — detached / attached SignedData, original-DER `signedAttrs` verification, BER ([docs](https://jktantan.github.io/sm-crypto-wasm/en/guide/cms));
+- **WebCrypto** — a `subtle`-style subset: SM3 / HMAC(SM3) / SM2 / SM4 ([docs](https://jktantan.github.io/sm-crypto-wasm/en/guide/webcrypto)).
+
+No certificate-chain validation or CRL/OCSP for X.509/CMS; the WebCrypto adapter is not a polyfill of native `crypto.subtle`.
+
+---
+
 ## API at a glance
 
 | Module | Functions |
 |---|---|
-| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `preparePublicKey` (async) · `configurePreparedKeyCache` · `clearPreparedPublicKeys` · `getPreparedPublicKeys` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `webcrypto` | `subtle` · `CryptoKey` |
+| `cms` | `signData` · `verifySignedData` · `parseSignedData` · `CmsError` |
+| `x509` | `parseCertificate` · `parseCertificates` · `createSelfSignedCertificate` · `issueCertificate` · `parseDistinguishedName` · `verifyCertificateSignature` |
 | `sm3` | `hash` · `hmac` |
 | `sm4` | `encryptECB` / `decryptECB` · `encryptCBC` / `decryptCBC` · `encryptCTR` / `decryptCTR` · `encryptCFB` / `decryptCFB` · `encryptOFB` / `decryptOFB` · `encryptGCM` / `decryptGCM` |
 | `sm9` | `generateKeyPair` (async) · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
@@ -594,7 +636,7 @@ import { hash } from 'sm-crypto-wasm/sm3';
 import { encryptCBC } from 'sm-crypto-wasm/sm4';
 ```
 
-Available sub-paths: `sm-crypto-wasm/sm2` · `/sm3` · `/sm4` · `/sm9` · `/zuc`.
+Available sub-paths: `sm-crypto-wasm/sm2` · `/sm3` · `/sm4` · `/sm9` · `/x509` · `/cms` · `/webcrypto` · `/zuc`.
 
 ---
 
@@ -961,11 +1003,32 @@ zuc.zucMac(key, macIv, '616263');               // → 4-байтовый тег
 
 ---
 
+### X.509 · CMS · WebCrypto
+
+```ts
+import { x509, cms, webcrypto } from 'sm-crypto-wasm';
+
+const cert = x509.parseCertificate(pem);
+const signed = cms.signData({ data, privateKey, certificate: cert });
+const digest = await webcrypto.subtle.digest('SM3', data);
+```
+
+- **X.509** — разбор, проверка одного сертификата, самоподпись / выпуск через простой CA ([документация](https://jktantan.github.io/sm-crypto-wasm/ru/guide/x509));
+- **CMS** — detached / attached SignedData, проверка по исходным DER `signedAttrs`, BER ([документация](https://jktantan.github.io/sm-crypto-wasm/ru/guide/cms));
+- **WebCrypto** — подмножество в стиле `subtle`: SM3 / HMAC(SM3) / SM2 / SM4 ([документация](https://jktantan.github.io/sm-crypto-wasm/ru/guide/webcrypto)).
+
+Для X.509 / CMS нет проверки цепочки и CRL/OCSP; WebCrypto — не polyfill нативного `crypto.subtle`.
+
+---
+
 ## Сводка API
 
 | Модуль | Функции |
 |---|---|
-| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `preparePublicKey` (async) · `configurePreparedKeyCache` · `clearPreparedPublicKeys` · `getPreparedPublicKeys` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `webcrypto` | `subtle` · `CryptoKey` |
+| `cms` | `signData` · `verifySignedData` · `parseSignedData` · `CmsError` |
+| `x509` | `parseCertificate` · `parseCertificates` · `createSelfSignedCertificate` · `issueCertificate` · `parseDistinguishedName` · `verifyCertificateSignature` |
 | `sm3` | `hash` · `hmac` |
 | `sm4` | `encryptECB` / `decryptECB` · `encryptCBC` / `decryptCBC` · `encryptCTR` / `decryptCTR` · `encryptCFB` / `decryptCFB` · `encryptOFB` / `decryptOFB` · `encryptGCM` / `decryptGCM` |
 | `sm9` | `generateKeyPair` (async) · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
@@ -989,7 +1052,7 @@ import { hash } from 'sm-crypto-wasm/sm3';
 import { encryptCBC } from 'sm-crypto-wasm/sm4';
 ```
 
-Доступные подпути: `sm-crypto-wasm/sm2` · `/sm3` · `/sm4` · `/sm9` · `/zuc`.
+Доступные подпути: `sm-crypto-wasm/sm2` · `/sm3` · `/sm4` · `/sm9` · `/x509` · `/cms` · `/webcrypto` · `/zuc`.
 
 ---
 
@@ -1156,4 +1219,4 @@ biome).
 - [gmkit / gmkitx](https://github.com/gmkits/gmkit) — источник, из
   которого портирована реализация ZUC.
 
-</details>
+</details>

package/dist/asn1/decode.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ASN.1 DER/BER 解析器。
+ *
+ * 覆盖 X.509 与 CMS 需要的 BER/DER 子集：
+ * - definite-length（短/长格式）；
+ * - BER indefinite-length（`0x80` + EOC `00 00`），**仅 `parseBer` 允许**；
+ * - 高 tag number（`0x1f` + base128）；
+ * - constructed / primitive 递归。
+ *
+ * 严格性：
+ * - `parseDer` 拒绝 indefinite、非最小长度编码、EOC、尾部多余字节；
+ * - `parseBer` 放宽长度编码并允许 indefinite，但仍拒绝截断与尾部多余字节；
+ * - 单对象解析一律拒绝尾部多余字节（红线 #3）。
+ *
+ * 每个节点保留 `raw`（输入缓冲上的视图），供 CMS 验签与证书 TBS 直接使用。
+ */
+import { type Asn1Node } from './types.js';
+/** 解析选项。 */
+export interface ParseOptions {
+    /** 允许 BER indefinite-length。仅 CMS 路径应开启。 */
+    allowIndefinite?: boolean;
+    /** 是否严格校验长度编码的最小形式（DER 默认开启）。 */
+    strictLength?: boolean;
+}
+/**
+ * 解析单个 DER 对象。
+ *
+ * @throws Asn1Error 截断、超出深度、非 DER 编码、或根节点后有多余字节。
+ */
+export declare function parseDer(buf: Uint8Array): Asn1Node;
+/**
+ * 解析单个 BER 对象（允许 indefinite-length）。
+ *
+ * @throws Asn1Error 截断、超出深度、或根节点后有多余字节。
+ */
+export declare function parseBer(buf: Uint8Array): Asn1Node;
+/**
+ * 解析连续的多个 DER 对象（证书 bundle / CMS 文件）。
+ *
+ * 返回按出现顺序排列的节点；允许空输入并返回空数组。
+ */
+export declare function parseDerAll(buf: Uint8Array): Asn1Node[];
+/** 解析连续的多个 BER 对象（允许 indefinite-length）。 */
+export declare function parseBerAll(buf: Uint8Array): Asn1Node[];
+/**
+ * 读取 INTEGER（二进制补码，支持负数）。
+ *
+ * @throws Asn1Error 节点不是 INTEGER。
+ */
+export declare function readInteger(node: Asn1Node, what?: string): bigint;
+/** 读取 BOOLEAN（DER 中 TRUE 必须为 0xFF）。 */
+export declare function readBoolean(node: Asn1Node, what?: string): boolean;
+/** BIT STRING 内容。 */
+export interface BitString {
+    /** 去掉 unused bits 后的有效字节（尾部未用位保留，由调用方屏蔽）。 */
+    readonly bytes: Uint8Array;
+    /** 末尾未使用位数（0..7）。 */
+    readonly unusedBits: number;
+}
+/** 读取 BIT STRING。 */
+export declare function readBitString(node: Asn1Node, what?: string): BitString;
+/** 读取 OCTET STRING。 */
+export declare function readOctetString(node: Asn1Node, what?: string): Uint8Array;
+/** 读取 OBJECT IDENTIFIER。 */
+export declare function readOid(node: Asn1Node, what?: string): string;
+/** 读取 UTCTime / GeneralizedTime。 */
+export declare function readTime(node: Asn1Node, what?: string): Date;
+/**
+ * 读取 ASN.1 字符串。
+ *
+ * 支持 UTF8String / PrintableString / IA5String / NumericString /
+ * TeletexString / BMPString / UniversalString；其他类型抛 `Asn1Error`。
+ */
+export declare function readString(node: Asn1Node, what?: string): string;

package/dist/asn1/decode.js

@@ -0,0 +1,338 @@
+/**
+ * ASN.1 DER/BER 解析器。
+ *
+ * 覆盖 X.509 与 CMS 需要的 BER/DER 子集：
+ * - definite-length（短/长格式）；
+ * - BER indefinite-length（`0x80` + EOC `00 00`），**仅 `parseBer` 允许**；
+ * - 高 tag number（`0x1f` + base128）；
+ * - constructed / primitive 递归。
+ *
+ * 严格性：
+ * - `parseDer` 拒绝 indefinite、非最小长度编码、EOC、尾部多余字节；
+ * - `parseBer` 放宽长度编码并允许 indefinite，但仍拒绝截断与尾部多余字节；
+ * - 单对象解析一律拒绝尾部多余字节（红线 #3）。
+ *
+ * 每个节点保留 `raw`（输入缓冲上的视图），供 CMS 验签与证书 TBS 直接使用。
+ */
+import { decodeOid } from './oid.js';
+import { parseTime } from './time.js';
+import { Asn1Class, Asn1Error, UniversalTag } from './types.js';
+/** constructed 嵌套深度上限，防栈溢出与恶意深嵌套。 */
+const MAX_DEPTH = 64;
+/**
+ * 解析单个 DER 对象。
+ *
+ * @throws Asn1Error 截断、超出深度、非 DER 编码、或根节点后有多余字节。
+ */
+export function parseDer(buf) {
+    return parseSingle(buf, { allowIndefinite: false, strictLength: true }, 'parseDer');
+}
+/**
+ * 解析单个 BER 对象（允许 indefinite-length）。
+ *
+ * @throws Asn1Error 截断、超出深度、或根节点后有多余字节。
+ */
+export function parseBer(buf) {
+    return parseSingle(buf, { allowIndefinite: true, strictLength: false }, 'parseBer');
+}
+/**
+ * 解析连续的多个 DER 对象（证书 bundle / CMS 文件）。
+ *
+ * 返回按出现顺序排列的节点；允许空输入并返回空数组。
+ */
+export function parseDerAll(buf) {
+    return parseAll(buf, { allowIndefinite: false, strictLength: true }, 'parseDerAll');
+}
+/** 解析连续的多个 BER 对象（允许 indefinite-length）。 */
+export function parseBerAll(buf) {
+    return parseAll(buf, { allowIndefinite: true, strictLength: false }, 'parseBerAll');
+}
+function parseSingle(buf, opts, where) {
+    const reader = new Reader(buf, opts, where);
+    const node = reader.readNode(0);
+    if (reader.remaining() !== 0) {
+        throw new Asn1Error(`${where}: ${reader.remaining()} trailing bytes after root node`);
+    }
+    return node;
+}
+function parseAll(buf, opts, where) {
+    const reader = new Reader(buf, opts, where);
+    const nodes = [];
+    while (reader.remaining() > 0) {
+        nodes.push(reader.readNode(0));
+    }
+    return nodes;
+}
+class Reader {
+    buf;
+    opts;
+    where;
+    pos = 0;
+    constructor(buf, opts, where) {
+        this.buf = buf;
+        this.opts = opts;
+        this.where = where;
+    }
+    remaining() {
+        return this.buf.length - this.pos;
+    }
+    byte() {
+        if (this.pos >= this.buf.length) {
+            throw new Asn1Error(`${this.where}: truncated at offset ${this.pos}`);
+        }
+        return this.buf[this.pos++];
+    }
+    /** 读取一个完整 TLV。 */
+    readNode(depth) {
+        if (depth > MAX_DEPTH) {
+            throw new Asn1Error(`${this.where}: nesting deeper than ${MAX_DEPTH}`);
+        }
+        const start = this.pos;
+        const first = this.byte();
+        const cls = ((first >> 6) & 0x03);
+        const constructed = (first & 0x20) !== 0;
+        const tag = (first & 0x1f) === 0x1f ? this.readHighTag() : first & 0x1f;
+        // EndOfContent 只能作为 indefinite-length 的结束标记出现。
+        if (cls === Asn1Class.Universal && tag === UniversalTag.EndOfContent && !constructed) {
+            const lb = this.byte();
+            if (lb !== 0)
+                throw new Asn1Error(`${this.where}: malformed EndOfContent`);
+            throw new Asn1Error(`${this.where}: unexpected EndOfContent at offset ${start}`);
+        }
+        const lb = this.byte();
+        let length = 0;
+        let indefinite = false;
+        if (lb === 0x80) {
+            if (!this.opts.allowIndefinite) {
+                throw new Asn1Error(`${this.where}: indefinite-length encoding is not allowed`);
+            }
+            if (!constructed) {
+                throw new Asn1Error(`${this.where}: indefinite length on primitive tag ${tag}`);
+            }
+            indefinite = true;
+        }
+        else if (lb < 0x80) {
+            length = lb;
+        }
+        else {
+            length = this.readLongLength(lb & 0x7f);
+        }
+        const contentStart = this.pos;
+        if (indefinite) {
+            // indefinite：一直读到 EOC（00 00）。
+            const children = [];
+            for (;;) {
+                if (this.remaining() < 2) {
+                    throw new Asn1Error(`${this.where}: truncated indefinite-length content`);
+                }
+                if (this.buf[this.pos] === 0 && this.buf[this.pos + 1] === 0) {
+                    this.pos += 2;
+                    break;
+                }
+                children.push(this.readNode(depth + 1));
+            }
+            const contentEnd = this.pos - 2;
+            const value = this.buf.subarray(contentStart, contentEnd);
+            return {
+                cls,
+                tag,
+                constructed,
+                indefinite,
+                length: value.length,
+                value,
+                children,
+                raw: this.buf.subarray(start, this.pos),
+            };
+        }
+        if (this.pos + length > this.buf.length) {
+            throw new Asn1Error(`${this.where}: truncated value, need ${length} bytes at offset ${this.pos}`);
+        }
+        this.pos += length;
+        const value = this.buf.subarray(contentStart, contentStart + length);
+        if (constructed) {
+            const inner = new Reader(value, this.opts, this.where);
+            const children = [];
+            while (inner.remaining() > 0) {
+                children.push(inner.readNode(depth + 1));
+            }
+            return {
+                cls,
+                tag,
+                constructed,
+                indefinite,
+                length,
+                value,
+                children,
+                raw: this.buf.subarray(start, this.pos),
+            };
+        }
+        return {
+            cls,
+            tag,
+            constructed,
+            indefinite,
+            length,
+            value,
+            raw: this.buf.subarray(start, this.pos),
+        };
+    }
+    /** 高 tag number：后续字节 base128。 */
+    readHighTag() {
+        let value = 0;
+        let count = 0;
+        for (;;) {
+            const b = this.byte();
+            if (count === 0 && b === 0x80) {
+                throw new Asn1Error(`${this.where}: non-minimal high tag number`);
+            }
+            if (count >= 4) {
+                throw new Asn1Error(`${this.where}: tag number too large`);
+            }
+            value = value * 128 + (b & 0x7f);
+            count++;
+            if ((b & 0x80) === 0)
+                return value;
+        }
+    }
+    /** 长格式长度（`n` 为 1..4）。 */
+    readLongLength(n) {
+        if (n === 0)
+            throw new Asn1Error(`${this.where}: reserved length encoding 0x80`);
+        if (n > 4)
+            throw new Asn1Error(`${this.where}: length of ${n} bytes is not supported`);
+        const lengthStart = this.pos;
+        let length = 0;
+        for (let i = 0; i < n; i++) {
+            length = length * 256 + this.byte();
+        }
+        if (length < 0 || !Number.isSafeInteger(length)) {
+            throw new Asn1Error(`${this.where}: length out of range`);
+        }
+        if (this.opts.strictLength) {
+            if (this.buf[lengthStart] === 0) {
+                throw new Asn1Error(`${this.where}: non-minimal long-form length (leading zero)`);
+            }
+            if (length < 0x80) {
+                throw new Asn1Error(`${this.where}: non-minimal long-form length ${length}`);
+            }
+        }
+        return length;
+    }
+}
+// ----------------- 常用值读取 -----------------
+/**
+ * 读取 INTEGER（二进制补码，支持负数）。
+ *
+ * @throws Asn1Error 节点不是 INTEGER。
+ */
+export function readInteger(node, what = 'INTEGER') {
+    if (node.cls !== Asn1Class.Universal || node.tag !== UniversalTag.Integer) {
+        throw new Asn1Error(`${what}: expected INTEGER`);
+    }
+    if (node.value.length === 0)
+        throw new Asn1Error(`${what}: empty INTEGER`);
+    let value = 0n;
+    for (let i = 0; i < node.value.length; i++) {
+        value = (value << 8n) | BigInt(node.value[i]);
+    }
+    if ((node.value[0] & 0x80) !== 0) {
+        value -= 1n << BigInt(node.value.length * 8);
+    }
+    return value;
+}
+/** 读取 BOOLEAN（DER 中 TRUE 必须为 0xFF）。 */
+export function readBoolean(node, what = 'BOOLEAN') {
+    if (node.cls !== Asn1Class.Universal || node.tag !== UniversalTag.Boolean) {
+        throw new Asn1Error(`${what}: expected BOOLEAN`);
+    }
+    if (node.value.length !== 1)
+        throw new Asn1Error(`${what}: BOOLEAN must be 1 byte`);
+    return node.value[0] !== 0;
+}
+/** 读取 BIT STRING。 */
+export function readBitString(node, what = 'BIT STRING') {
+    if (node.cls !== Asn1Class.Universal || node.tag !== UniversalTag.BitString) {
+        throw new Asn1Error(`${what}: expected BIT STRING`);
+    }
+    if (node.value.length === 0)
+        throw new Asn1Error(`${what}: empty BIT STRING`);
+    const unusedBits = node.value[0];
+    if (unusedBits > 7)
+        throw new Asn1Error(`${what}: invalid unused-bit count ${unusedBits}`);
+    return { bytes: node.value.subarray(1), unusedBits };
+}
+/** 读取 OCTET STRING。 */
+export function readOctetString(node, what = 'OCTET STRING') {
+    if (node.cls !== Asn1Class.Universal || node.tag !== UniversalTag.OctetString) {
+        throw new Asn1Error(`${what}: expected OCTET STRING`);
+    }
+    return node.value;
+}
+/** 读取 OBJECT IDENTIFIER。 */
+export function readOid(node, what = 'OBJECT IDENTIFIER') {
+    if (node.cls !== Asn1Class.Universal || node.tag !== UniversalTag.ObjectIdentifier) {
+        throw new Asn1Error(`${what}: expected OBJECT IDENTIFIER`);
+    }
+    return decodeOid(node.value);
+}
+/** 读取 UTCTime / GeneralizedTime。 */
+export function readTime(node, what = 'Time') {
+    if (node.cls !== Asn1Class.Universal) {
+        throw new Asn1Error(`${what}: expected UTCTime or GeneralizedTime`);
+    }
+    if (node.tag !== UniversalTag.UtcTime && node.tag !== UniversalTag.GeneralizedTime) {
+        throw new Asn1Error(`${what}: expected UTCTime or GeneralizedTime`);
+    }
+    const text = latin1(node.value);
+    return parseTime(text);
+}
+/**
+ * 读取 ASN.1 字符串。
+ *
+ * 支持 UTF8String / PrintableString / IA5String / NumericString /
+ * TeletexString / BMPString / UniversalString；其他类型抛 `Asn1Error`。
+ */
+export function readString(node, what = 'string') {
+    if (node.cls !== Asn1Class.Universal) {
+        throw new Asn1Error(`${what}: expected a UNIVERSAL string type`);
+    }
+    switch (node.tag) {
+        case UniversalTag.Utf8String:
+            return new TextDecoder('utf-8', { fatal: true }).decode(node.value);
+        case UniversalTag.PrintableString:
+        case UniversalTag.Ia5String:
+        case UniversalTag.NumericString:
+        case UniversalTag.TeletexString:
+            return latin1(node.value);
+        case UniversalTag.BmpString: {
+            if (node.value.length % 2 !== 0)
+                throw new Asn1Error(`${what}: odd-length BMPString`);
+            let out = '';
+            for (let i = 0; i < node.value.length; i += 2) {
+                out += String.fromCharCode((node.value[i] << 8) | node.value[i + 1]);
+            }
+            return out;
+        }
+        case UniversalTag.UniversalString: {
+            if (node.value.length % 4 !== 0)
+                throw new Asn1Error(`${what}: bad UniversalString`);
+            let out = '';
+            for (let i = 0; i < node.value.length; i += 4) {
+                const cp = node.value[i] * 0x1000000 +
+                    (node.value[i + 1] << 16) +
+                    (node.value[i + 2] << 8) +
+                    node.value[i + 3];
+                out += String.fromCodePoint(cp);
+            }
+            return out;
+        }
+        default:
+            throw new Asn1Error(`${what}: unsupported string tag ${node.tag}`);
+    }
+}
+function latin1(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i++)
+        out += String.fromCharCode(bytes[i]);
+    return out;
+}

package/dist/asn1/encode.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ASN.1 DER 编码器与构造器。
+ *
+ * 规则：
+ * - `encode()` 按 `cls + constructed + tag` 重建首字节（修复旧实现丢掉
+ *   constructed 位的问题），对 constructed 节点递归编码子节点；
+ * - SET OF 按编码字节排序（DER 要求）；
+ * - BOOLEAN TRUE 编码为 0xFF；
+ * - INTEGER 使用最小补码编码；
+ * - 输出始终是 definite-length（BER indefinite 只在解析侧接受）。
+ */
+import { Asn1Class, type Asn1Node } from './types.js';
+/** 编码单个节点为 DER 字节。 */
+export declare function encode(node: Asn1Node): Uint8Array;
+/**
+ * `encode` 的旧名（兼容 `src/pem/asn1.ts` 的历史导出）。
+ *
+ * @deprecated 使用 `encode`。
+ */
+export declare const encodeDer: typeof encode;
+/** 编码 tag 首字节（含高 tag number 的 base128 展开）。 */
+export declare function encodeTag(cls: Asn1Class, constructed: boolean, tag: number): Uint8Array;
+/** 编码 definite-length。 */
+export declare function encodeLength(length: number): Uint8Array;
+/** 构造 SEQUENCE。 */
+export declare function seq(children: readonly Asn1Node[]): Asn1Node;
+/** 构造 SET（保持给定顺序；ASN.1 SET 的排序语义由调用方负责）。 */
+export declare function set(children: readonly Asn1Node[]): Asn1Node;
+/** 构造 SET OF（按 DER 编码字节排序）。 */
+export declare function setOf(children: readonly Asn1Node[]): Asn1Node;
+/** 构造 `[tag] EXPLICIT` 包装。 */
+export declare function explicit(tag: number, inner: Asn1Node): Asn1Node;
+/**
+ * 构造 `[tag] IMPLICIT` 包装：只替换外层标签，内容保持不变。
+ */
+export declare function implicit(tag: number, inner: Asn1Node, cls?: Asn1Class): Asn1Node;
+/** 构造 BIT STRING。`unusedBits` 为末尾未使用位数（0..7）。 */
+export declare function bitString(bytes: Uint8Array, unusedBits?: number): Asn1Node;
+/** 构造 OCTET STRING。 */
+export declare function octetString(bytes: Uint8Array): Asn1Node;
+/** 构造 BOOLEAN。 */
+export declare function boolean(value: boolean): Asn1Node;
+/** 构造 NULL。 */
+export declare function nullValue(): Asn1Node;
+/** 构造 INTEGER（最小补码编码）。 */
+export declare function integer(value: bigint | number): Asn1Node;
+/** 构造 OBJECT IDENTIFIER。 */
+export declare function oid(value: string): Asn1Node;
+/** 构造 UTF8String。 */
+export declare function utf8String(value: string): Asn1Node;
+/** 构造 PrintableString（仅允许 A-Z a-z 0-9 与 `'()+,-./:=?` 和空格）。 */
+export declare function printableString(value: string): Asn1Node;
+/** 构造 IA5String（仅 ASCII）。 */
+export declare function ia5String(value: string): Asn1Node;
+/** 构造 UTCTime（1950–2049）。 */
+export declare function utcTime(date: Date): Asn1Node;
+/** 构造 GeneralizedTime。 */
+export declare function generalizedTime(date: Date): Asn1Node;
+/** 按 RFC 5280 自动选择 UTCTime / GeneralizedTime。 */
+export declare function time(date: Date): Asn1Node;
+/**
+ * INTEGER 最小补码编码。
+ *
+ * - 0 → `00`；
+ * - 正数：最高位为 1 时前置 `00`；
+ * - 负数：选择最少字节数 n 使 `-2^(8n-1) <= v`，按 2^(8n) 取模。
+ */
+export declare function encodeIntegerValue(v: bigint): Uint8Array;