sm-crypto-wasm 0.3.0 → 0.7.0

package/dist/asn1/encode.js

@@ -0,0 +1,275 @@
+/**
+ * ASN.1 DER 编码器与构造器。
+ *
+ * 规则：
+ * - `encode()` 按 `cls + constructed + tag` 重建首字节（修复旧实现丢掉
+ *   constructed 位的问题），对 constructed 节点递归编码子节点；
+ * - SET OF 按编码字节排序（DER 要求）；
+ * - BOOLEAN TRUE 编码为 0xFF；
+ * - INTEGER 使用最小补码编码；
+ * - 输出始终是 definite-length（BER indefinite 只在解析侧接受）。
+ */
+import { encodeOid } from './oid.js';
+import { encodeGeneralizedTime, encodeTime, encodeUtcTime } from './time.js';
+import { Asn1Class, Asn1Error, UniversalTag } from './types.js';
+// ----------------- 基础编码 -----------------
+/** 编码单个节点为 DER 字节。 */
+export function encode(node) {
+    const constructed = node.children !== undefined ? true : node.constructed;
+    const value = constructed
+        ? node.children
+            ? concat(node.children.map((child) => encode(child)))
+            : node.value
+        : node.value;
+    const header = concat([encodeTag(node.cls, constructed, node.tag), encodeLength(value.length)]);
+    return concat([header, value]);
+}
+/**
+ * `encode` 的旧名（兼容 `src/pem/asn1.ts` 的历史导出）。
+ *
+ * @deprecated 使用 `encode`。
+ */
+export const encodeDer = encode;
+/** 编码 tag 首字节（含高 tag number 的 base128 展开）。 */
+export function encodeTag(cls, constructed, tag) {
+    if (!Number.isInteger(tag) || tag < 0) {
+        throw new Asn1Error(`encodeTag: invalid tag ${tag}`);
+    }
+    const base = (cls << 6) | (constructed ? 0x20 : 0);
+    if (tag < 0x1f)
+        return new Uint8Array([base | tag]);
+    const out = [base | 0x1f];
+    let v = tag;
+    const groups = [];
+    do {
+        groups.unshift(v % 128);
+        v = Math.floor(v / 128);
+    } while (v > 0);
+    for (let i = 0; i < groups.length - 1; i++)
+        groups[i] = groups[i] | 0x80;
+    out.push(...groups);
+    return new Uint8Array(out);
+}
+/** 编码 definite-length。 */
+export function encodeLength(length) {
+    if (!Number.isInteger(length) || length < 0) {
+        throw new Asn1Error(`encodeLength: bad length ${length}`);
+    }
+    if (length < 0x80)
+        return new Uint8Array([length]);
+    const bytes = [];
+    let v = length;
+    while (v > 0) {
+        bytes.unshift(v % 256);
+        v = Math.floor(v / 256);
+    }
+    return new Uint8Array([0x80 | bytes.length, ...bytes]);
+}
+// ----------------- 构造器 -----------------
+/** 构造 SEQUENCE。 */
+export function seq(children) {
+    return makeConstructed(Asn1Class.Universal, UniversalTag.Sequence, children);
+}
+/** 构造 SET（保持给定顺序；ASN.1 SET 的排序语义由调用方负责）。 */
+export function set(children) {
+    return makeConstructed(Asn1Class.Universal, UniversalTag.Set, children);
+}
+/** 构造 SET OF（按 DER 编码字节排序）。 */
+export function setOf(children) {
+    const sorted = children
+        .map((node) => ({ node, bytes: encode(node) }))
+        .sort((a, b) => compareBytes(a.bytes, b.bytes))
+        .map((entry) => entry.node);
+    return makeConstructed(Asn1Class.Universal, UniversalTag.Set, sorted);
+}
+/** 构造 `[tag] EXPLICIT` 包装。 */
+export function explicit(tag, inner) {
+    const value = encode(inner);
+    return {
+        cls: Asn1Class.ContextSpecific,
+        tag,
+        constructed: true,
+        indefinite: false,
+        length: value.length,
+        value,
+        children: [inner],
+        raw: concat([
+            encodeTag(Asn1Class.ContextSpecific, true, tag),
+            encodeLength(value.length),
+            value,
+        ]),
+    };
+}
+/**
+ * 构造 `[tag] IMPLICIT` 包装：只替换外层标签，内容保持不变。
+ */
+export function implicit(tag, inner, cls = Asn1Class.ContextSpecific) {
+    const constructed = inner.children !== undefined ? true : inner.constructed;
+    const value = inner.children ? concat(inner.children.map((child) => encode(child))) : inner.value;
+    return {
+        cls,
+        tag,
+        constructed,
+        indefinite: false,
+        length: value.length,
+        value,
+        children: inner.children,
+        raw: concat([encodeTag(cls, constructed, tag), encodeLength(value.length), value]),
+    };
+}
+/** 构造 BIT STRING。`unusedBits` 为末尾未使用位数（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}`);
+    }
+    const value = new Uint8Array(bytes.length + 1);
+    value[0] = unusedBits;
+    value.set(bytes, 1);
+    return makePrimitive(UniversalTag.BitString, value);
+}
+/** 构造 OCTET STRING。 */
+export function octetString(bytes) {
+    return makePrimitive(UniversalTag.OctetString, bytes);
+}
+/** 构造 BOOLEAN。 */
+export function boolean(value) {
+    return makePrimitive(UniversalTag.Boolean, new Uint8Array([value ? 0xff : 0x00]));
+}
+/** 构造 NULL。 */
+export function nullValue() {
+    return makePrimitive(UniversalTag.Null, new Uint8Array(0));
+}
+/** 构造 INTEGER（最小补码编码）。 */
+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。 */
+export function oid(value) {
+    return makePrimitive(UniversalTag.ObjectIdentifier, encodeOid(value));
+}
+/** 构造 UTF8String。 */
+export function utf8String(value) {
+    return makePrimitive(UniversalTag.Utf8String, new TextEncoder().encode(value));
+}
+/** 构造 PrintableString（仅允许 A-Z a-z 0-9 与 `'()+,-./:=?` 和空格）。 */
+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）。 */
+export function ia5String(value) {
+    for (let i = 0; i < value.length; i++) {
+        if (value.charCodeAt(i) > 0x7f) {
+            throw new Asn1Error('ia5String: non-ASCII character');
+        }
+    }
+    return makePrimitive(UniversalTag.Ia5String, asciiBytes(value));
+}
+/** 构造 UTCTime（1950–2049）。 */
+export function utcTime(date) {
+    return makePrimitive(UniversalTag.UtcTime, asciiBytes(encodeUtcTime(date)));
+}
+/** 构造 GeneralizedTime。 */
+export function generalizedTime(date) {
+    return makePrimitive(UniversalTag.GeneralizedTime, asciiBytes(encodeGeneralizedTime(date)));
+}
+/** 按 RFC 5280 自动选择 UTCTime / GeneralizedTime。 */
+export function time(date) {
+    return makePrimitive(isUtcYear(date) ? UniversalTag.UtcTime : UniversalTag.GeneralizedTime, asciiBytes(encodeTime(date)));
+}
+// ----------------- 内部 -----------------
+function makePrimitive(tag, value) {
+    return {
+        cls: Asn1Class.Universal,
+        tag,
+        constructed: false,
+        indefinite: false,
+        length: value.length,
+        value,
+        raw: concat([encodeTag(Asn1Class.Universal, false, tag), encodeLength(value.length), value]),
+    };
+}
+function makeConstructed(cls, tag, children) {
+    const value = concat(children.map((child) => encode(child)));
+    return {
+        cls,
+        tag,
+        constructed: true,
+        indefinite: false,
+        length: value.length,
+        value,
+        children,
+        raw: concat([encodeTag(cls, true, tag), encodeLength(value.length), value]),
+    };
+}
+function isUtcYear(date) {
+    if (!(date instanceof Date) || Number.isNaN(date.getTime()))
+        return false;
+    const year = date.getUTCFullYear();
+    return year >= 1950 && year <= 2049;
+}
+/**
+ * INTEGER 最小补码编码。
+ *
+ * - 0 → `00`；
+ * - 正数：最高位为 1 时前置 `00`；
+ * - 负数：选择最少字节数 n 使 `-2^(8n-1) <= v`，按 2^(8n) 取模。
+ */
+export function encodeIntegerValue(v) {
+    if (v === 0n)
+        return new Uint8Array([0]);
+    if (v > 0n) {
+        let n = 1;
+        while (v >= 1n << BigInt(8 * n - 1))
+            n++;
+        const out = new Uint8Array(n);
+        let x = v;
+        for (let i = n - 1; i >= 0; i--) {
+            out[i] = Number(x & 0xffn);
+            x >>= 8n;
+        }
+        return out;
+    }
+    let n = 1;
+    while (v < -(1n << BigInt(8 * n - 1)))
+        n++;
+    let x = (1n << BigInt(8 * n)) + v;
+    const out = new Uint8Array(n);
+    for (let i = n - 1; i >= 0; i--) {
+        out[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    return out;
+}
+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;
+}
+function compareBytes(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const d = a[i] - b[i];
+        if (d !== 0)
+            return d;
+    }
+    return a.length - b.length;
+}
+function concat(parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const p of parts) {
+        out.set(p, offset);
+        offset += p.length;
+    }
+    return out;
+}

package/dist/asn1/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ASN.1 内部层 barrel。
+ *
+ * **不进入主入口导出**（spec Anti-Goal：不公开底层 DER/大数接口）。
+ * `src/pem/asn1.ts` 仍按旧符号名 re-export 本层，供 PEM/PKCS#8 代码与测试使用。
+ */
+export * from './decode.js';
+export * from './encode.js';
+export * from './oid.js';
+export * from './time.js';
+export * from './types.js';

package/dist/asn1/index.js

@@ -0,0 +1,11 @@
+/**
+ * ASN.1 内部层 barrel。
+ *
+ * **不进入主入口导出**（spec Anti-Goal：不公开底层 DER/大数接口）。
+ * `src/pem/asn1.ts` 仍按旧符号名 re-export 本层，供 PEM/PKCS#8 代码与测试使用。
+ */
+export * from './decode.js';
+export * from './encode.js';
+export * from './oid.js';
+export * from './time.js';
+export * from './types.js';

package/dist/asn1/oid.d.ts

@@ -0,0 +1,22 @@
+/**
+ * OBJECT IDENTIFIER 编解码。
+ *
+ * 与旧实现的差异：
+ * - 用 `bigint` 累加，不再受 32 位按位运算限制（`1.2.840.113549...` 这类
+ *   长组件不会溢出）；
+ * - 首个子标识符也走 base128 编码，支持 `2.999` 这类第二组件 ≥ 40 的 OID；
+ * - 解码时拒绝截断、空输入与非最小（前导 0x80）编码。
+ */
+/**
+ * 点分 OID → 内容字节（不含 tag 与 length）。
+ *
+ * @param oid 形如 `"1.2.156.10197.1.100"`。
+ * @throws Asn1Error 格式非法或组件越界。
+ */
+export declare function encodeOid(oid: string): Uint8Array;
+/**
+ * 内容字节 → 点分 OID。
+ *
+ * @throws Asn1Error 空输入、截断或非法 base128 编码。
+ */
+export declare function decodeOid(bytes: Uint8Array): string;

package/dist/asn1/oid.js

@@ -0,0 +1,107 @@
+/**
+ * OBJECT IDENTIFIER 编解码。
+ *
+ * 与旧实现的差异：
+ * - 用 `bigint` 累加，不再受 32 位按位运算限制（`1.2.840.113549...` 这类
+ *   长组件不会溢出）；
+ * - 首个子标识符也走 base128 编码，支持 `2.999` 这类第二组件 ≥ 40 的 OID；
+ * - 解码时拒绝截断、空输入与非最小（前导 0x80）编码。
+ */
+import { Asn1Error } from './types.js';
+/**
+ * 点分 OID → 内容字节（不含 tag 与 length）。
+ *
+ * @param oid 形如 `"1.2.156.10197.1.100"`。
+ * @throws Asn1Error 格式非法或组件越界。
+ */
+export function encodeOid(oid) {
+    const parts = parseOidComponents(oid);
+    const first = parts[0] * 40n + parts[1];
+    const out = encodeBase128(first);
+    for (let i = 2; i < parts.length; i++) {
+        out.push(...encodeBase128(parts[i]));
+    }
+    return new Uint8Array(out);
+}
+/**
+ * 内容字节 → 点分 OID。
+ *
+ * @throws Asn1Error 空输入、截断或非法 base128 编码。
+ */
+export function decodeOid(bytes) {
+    if (bytes.length === 0)
+        throw new Asn1Error('decodeOid: empty');
+    const values = [];
+    let value = 0n;
+    let pending = false;
+    for (let i = 0; i < bytes.length; i++) {
+        const octet = bytes[i] ?? 0;
+        // 每个子标识符的编码不得以 0x80 开头（非最小编码）。
+        if (!pending && octet === 0x80) {
+            throw new Asn1Error('decodeOid: non-minimal base128 encoding');
+        }
+        value = (value << 7n) | BigInt(octet & 0x7f);
+        pending = (octet & 0x80) !== 0;
+        if (!pending) {
+            values.push(value);
+            value = 0n;
+        }
+    }
+    if (pending)
+        throw new Asn1Error('decodeOid: truncated base128 component');
+    const first = values[0];
+    let a;
+    let b;
+    if (first < 40n) {
+        a = 0n;
+        b = first;
+    }
+    else if (first < 80n) {
+        a = 1n;
+        b = first - 40n;
+    }
+    else {
+        a = 2n;
+        b = first - 80n;
+    }
+    const parts = [a, b, ...values.slice(1)];
+    return parts.map((v) => v.toString(10)).join('.');
+}
+function parseOidComponents(oid) {
+    if (typeof oid !== 'string' || oid.length === 0) {
+        throw new Asn1Error(`encodeOid: bad oid "${String(oid)}"`);
+    }
+    const raw = oid.split('.');
+    if (raw.length < 2)
+        throw new Asn1Error(`encodeOid: bad oid "${oid}"`);
+    const parts = [];
+    for (const item of raw) {
+        if (!/^(0|[1-9][0-9]*)$/.test(item)) {
+            throw new Asn1Error(`encodeOid: bad component "${item}" in "${oid}"`);
+        }
+        parts.push(BigInt(item));
+    }
+    const first = parts[0];
+    const second = parts[1];
+    if (first > 2n)
+        throw new Asn1Error(`encodeOid: first component must be 0..2, got ${first}`);
+    if (first < 2n && second > 39n) {
+        throw new Asn1Error(`encodeOid: second component must be 0..39 for arc ${first}, got ${second}`);
+    }
+    return parts;
+}
+/** 无符号 bigint → base128 字节（高位 bit 为续行标志）。 */
+function encodeBase128(value) {
+    if (value < 0n)
+        throw new Asn1Error(`encodeBase128: negative value ${value}`);
+    const groups = [];
+    let v = value;
+    do {
+        groups.unshift(Number(v & 0x7fn));
+        v >>= 7n;
+    } while (v > 0n);
+    for (let i = 0; i < groups.length - 1; i++) {
+        groups[i] = groups[i] | 0x80;
+    }
+    return groups;
+}

package/dist/asn1/time.d.ts

@@ -0,0 +1,39 @@
+/**
+ * X.509 时间编码/解析（UTCTime / GeneralizedTime）。
+ *
+ * 规则（RFC 5280）：
+ * - 1950–2049 用 UTCTime（`YYMMDDHHMMSSZ`）；
+ * - 其余年份用 GeneralizedTime（`YYYYMMDDHHMMSSZ`）；
+ * - 证书时间精度到秒：解析时毫秒一律截断，保证 parse → encode round-trip。
+ *
+ * 解析刻意宽松（接受无秒、无时区、GeneralizedTime 的小数秒），因为真实现场
+ * 存在非规范编码；编码始终输出规范形式。
+ */
+/**
+ * 编码 UTCTime（仅接受 1950–2049 年）。
+ *
+ * @throws RangeError 日期无效或年份越界。
+ */
+export declare function encodeUtcTime(date: Date): string;
+/**
+ * 编码 GeneralizedTime。
+ *
+ * @throws RangeError 日期无效。
+ */
+export declare function encodeGeneralizedTime(date: Date): string;
+/**
+ * 按 RFC 5280 自动选择 UTCTime（1950–2049）或 GeneralizedTime。
+ */
+export declare function encodeTime(date: Date): string;
+/**
+ * 解析 UTCTime 或 GeneralizedTime 字符串。
+ *
+ * 接受：
+ * - `YYMMDDHHMMSSZ` / `YYMMDDHHMMZ`（UTCTime，50–99 → 1950–1999，00–49 → 2000–2049）；
+ * - `YYYYMMDDHHMMSSZ` / `YYYYMMDDHHMMZ` / `YYYYMMDDHHMMSS.sssZ`（GeneralizedTime）；
+ * - 时间部分可带 `+HHMM` / `-HHMM` 偏移；省略时区按 UTC 处理。
+ *
+ * @returns 毫秒为 0 的 `Date`。
+ * @throws Asn1Error 格式或日期分量非法。
+ */
+export declare function parseTime(text: string): Date;

package/dist/asn1/time.js

@@ -0,0 +1,111 @@
+/**
+ * X.509 时间编码/解析（UTCTime / GeneralizedTime）。
+ *
+ * 规则（RFC 5280）：
+ * - 1950–2049 用 UTCTime（`YYMMDDHHMMSSZ`）；
+ * - 其余年份用 GeneralizedTime（`YYYYMMDDHHMMSSZ`）；
+ * - 证书时间精度到秒：解析时毫秒一律截断，保证 parse → encode round-trip。
+ *
+ * 解析刻意宽松（接受无秒、无时区、GeneralizedTime 的小数秒），因为真实现场
+ * 存在非规范编码；编码始终输出规范形式。
+ */
+import { Asn1Error } from './types.js';
+/**
+ * 编码 UTCTime（仅接受 1950–2049 年）。
+ *
+ * @throws RangeError 日期无效或年份越界。
+ */
+export function encodeUtcTime(date) {
+    const { year, month, day, hour, minute, second } = utcParts(date, 'encodeUtcTime');
+    if (year < 1950 || year > 2049) {
+        throw new RangeError(`encodeUtcTime: year ${year} outside 1950..2049`);
+    }
+    const yy = year % 100;
+    return `${pad2(yy)}${pad2(month)}${pad2(day)}${pad2(hour)}${pad2(minute)}${pad2(second)}Z`;
+}
+/**
+ * 编码 GeneralizedTime。
+ *
+ * @throws RangeError 日期无效。
+ */
+export function encodeGeneralizedTime(date) {
+    const { year, month, day, hour, minute, second } = utcParts(date, 'encodeGeneralizedTime');
+    return `${pad4(year)}${pad2(month)}${pad2(day)}${pad2(hour)}${pad2(minute)}${pad2(second)}Z`;
+}
+/**
+ * 按 RFC 5280 自动选择 UTCTime（1950–2049）或 GeneralizedTime。
+ */
+export function encodeTime(date) {
+    const year = utcParts(date, 'encodeTime').year;
+    return year >= 1950 && year <= 2049 ? encodeUtcTime(date) : encodeGeneralizedTime(date);
+}
+/**
+ * 解析 UTCTime 或 GeneralizedTime 字符串。
+ *
+ * 接受：
+ * - `YYMMDDHHMMSSZ` / `YYMMDDHHMMZ`（UTCTime，50–99 → 1950–1999，00–49 → 2000–2049）；
+ * - `YYYYMMDDHHMMSSZ` / `YYYYMMDDHHMMZ` / `YYYYMMDDHHMMSS.sssZ`（GeneralizedTime）；
+ * - 时间部分可带 `+HHMM` / `-HHMM` 偏移；省略时区按 UTC 处理。
+ *
+ * @returns 毫秒为 0 的 `Date`。
+ * @throws Asn1Error 格式或日期分量非法。
+ */
+export function parseTime(text) {
+    const s = text.trim();
+    const m = /^(\d{2}|\d{4})(\d{2})(\d{2})(\d{2})(\d{2})?(\d{2})?([.,]\d+)?(Z|[+-]\d{4})?$/.exec(s);
+    if (!m)
+        throw new Asn1Error(`parseTime: unsupported time syntax "${text}"`);
+    const yearToken = m[1];
+    const year = yearToken.length === 2 ? utcYear(Number(yearToken)) : Number(yearToken);
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    const hour = Number(m[4]);
+    const minute = m[5] === undefined ? 0 : Number(m[5]);
+    const second = m[6] === undefined ? 0 : Number(m[6]);
+    const zone = m[8];
+    let offsetMinutes = 0;
+    if (zone !== undefined && zone !== 'Z') {
+        const sign = zone.startsWith('-') ? -1 : 1;
+        const oh = Number(zone.slice(1, 3));
+        const om = Number(zone.slice(3, 5));
+        if (oh > 23 || om > 59)
+            throw new Asn1Error(`parseTime: bad timezone offset "${zone}"`);
+        offsetMinutes = sign * (oh * 60 + om);
+    }
+    const localMs = Date.UTC(year, month - 1, day, hour, minute, second);
+    // 先在「输入的本地分量」上校验日期合法性，再应用时区偏移。
+    const local = new Date(localMs);
+    if (Number.isNaN(local.getTime()) ||
+        local.getUTCFullYear() !== year ||
+        local.getUTCMonth() !== month - 1 ||
+        local.getUTCDate() !== day ||
+        local.getUTCHours() !== hour ||
+        local.getUTCMinutes() !== minute ||
+        local.getUTCSeconds() !== second) {
+        throw new Asn1Error(`parseTime: invalid date components in "${text}"`);
+    }
+    return new Date(localMs - offsetMinutes * 60_000);
+}
+/** UTCTime 两位年份展开。 */
+function utcYear(yy) {
+    return yy >= 50 ? 1900 + yy : 2000 + yy;
+}
+function utcParts(date, where) {
+    if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+        throw new RangeError(`${where}: invalid Date`);
+    }
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+        hour: date.getUTCHours(),
+        minute: date.getUTCMinutes(),
+        second: date.getUTCSeconds(),
+    };
+}
+function pad2(n) {
+    return n.toString(10).padStart(2, '0');
+}
+function pad4(n) {
+    return n.toString(10).padStart(4, '0');
+}

package/dist/asn1/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ASN.1 通用类型与常量（DER/BER 子集）。
+ *
+ * 与旧 `src/pem/asn1.ts` 的关系：
+ * - 旧实现只覆盖 PKCS#8 用到的最小类型，且不保留 `constructed` 位；
+ * - 本层是 X.509 / CMS / WebCrypto 共用的通用基础设施，覆盖
+ *   BOOLEAN、SET、字符串、时间、context/application/private 标签等。
+ *
+ * 设计要点：
+ * - 每个节点保留 `raw`（含 tag + length + value 的原始切片），X.509 的 TBS
+ *   与 CMS 的 `signedAttrs` 验签必须对原始字节做摘要，不能重新编码；
+ * - `raw` 是对输入缓冲的**视图**（不拷贝），调用方不应假定其生命周期；
+ *   需要长期持有时自行 `slice()`；
+ * - 解析错误统一为 `Asn1Error`；上层（X.509/CMS）负责转换为各自的错误类型。
+ */
+/** ASN.1 标签类别。 */
+export type Asn1Class = 0 | 1 | 2 | 3;
+/** ASN.1 标签类别常量。 */
+export declare const Asn1Class: {
+    readonly Universal: 0;
+    readonly Application: 1;
+    readonly ContextSpecific: 2;
+    readonly Private: 3;
+};
+/** UNIVERSAL 类常用标签编号。 */
+export declare const UniversalTag: {
+    readonly EndOfContent: 0;
+    readonly Boolean: 1;
+    readonly Integer: 2;
+    readonly BitString: 3;
+    readonly OctetString: 4;
+    readonly Null: 5;
+    readonly ObjectIdentifier: 6;
+    readonly Enumerated: 10;
+    readonly Utf8String: 12;
+    readonly Sequence: 16;
+    readonly Set: 17;
+    readonly NumericString: 18;
+    readonly PrintableString: 19;
+    readonly TeletexString: 20;
+    readonly VideotexString: 21;
+    readonly Ia5String: 22;
+    readonly UtcTime: 23;
+    readonly GeneralizedTime: 24;
+    readonly UniversalString: 28;
+    readonly BmpString: 30;
+};
+/** ASN.1 节点。 */
+export interface Asn1Node {
+    /** 标签类别：UNIVERSAL=0、APPLICATION=1、CONTEXT=2、PRIVATE=3。 */
+    readonly cls: Asn1Class;
+    /** 标签编号（高 tag number 已展开为数值，不含 0x1f 标志位）。 */
+    readonly tag: number;
+    /** 是否为 constructed 编码。 */
+    readonly constructed: boolean;
+    /** 是否使用 BER indefinite-length（`0x80` + EOC）。DER 节点恒为 false。 */
+    readonly indefinite: boolean;
+    /** 内容字节数（indefinite 时为实际内容长度，不含 EOC）。 */
+    readonly length: number;
+    /** primitive 的 value；constructed 为子节点编码拼接后的内容字节。 */
+    readonly value: Uint8Array;
+    /** constructed 节点的子节点；primitive 为 `undefined`。 */
+    readonly children?: readonly Asn1Node[];
+    /** 节点原始字节（含 tag + length + value；indefinite 时含 EOC）。 */
+    readonly raw: Uint8Array;
+}
+/** ASN.1 解析/编码错误。 */
+export declare class Asn1Error extends Error {
+    readonly name = "Asn1Error";
+}
+/** 判断节点是否为指定 UNIVERSAL 类型。 */
+export declare function isUniversal(node: Asn1Node, tag: number): boolean;
+/** 断言节点为指定 UNIVERSAL 类型，否则抛 `Asn1Error`。 */
+export declare function expectUniversal(node: Asn1Node | undefined, tag: number, what: string): Asn1Node;
+/** 断言节点为 constructed SEQUENCE 并返回子节点。 */
+export declare function expectSequence(node: Asn1Node | undefined, what: string): readonly Asn1Node[];