sm-crypto-wasm 0.2.1 → 0.3.1

package/README.md

@@ -2,8 +2,6 @@
 
 [🇨🇳 中文](#zh-阅读下面的中文文档) · [🇺🇸 English](#en-english-documentation) · [🇷🇺 Русский](#ru-документация-на-русском)
 
-> 📖 **完整文档（含每个算法的参数表与可交互 Playground）**：<https://jktantan.github.io/sm-crypto-wasm/>
-
 Chinese cryptography standards (**SM2 / SM3 / SM4 / SM9 / ZUC**) implemented in
 **AssemblyScript → WebAssembly**. Works on Node 18+ and modern browsers (incl.
 Web Workers). Algorithms are split into sub-packages and lazy-loaded on demand.
@@ -110,6 +108,32 @@ sm2.decrypt(privateKeyPem, ct, { safeMode: true });     // 失败返回 null 而
 
 密钥也可以用裸 hex / `Uint8Array` 传入（32 字节私钥、64/65 字节公钥）。
 
+### SM2 —— 密钥封装与混合加密
+
+```ts
+import { sm2 } from 'sm-crypto-wasm';
+
+await sm2.ensureLoaded();
+
+// KEM：用公钥保护一把随机会话密钥（16 或 32 字节）。
+const { key, encapsulation } = sm2.kemEncrypt(publicKeyPem, 32);
+sm2.kemDecrypt(privateKeyPem, encapsulation, 32);       // === key
+
+// 混合加密：一次调用完成 KEM + SM4-GCM，适合大消息。
+// 返回版本化 sealed：version || klen || encapLen || encapsulation || iv || tag || ct
+const sealed = sm2.hybridEncrypt(publicKeyPem, '616263');
+sm2.hybridDecrypt(privateKeyPem, sealed);               // → '616263'（明文 hex）
+
+// sealed 也可转成自描述对象，便于调试或与手工组装互操作。
+const obj = sm2.sealedToObject(sealed);
+sm2.hybridDecrypt(privateKeyPem, sm2.sealedFromObject(obj));
+```
+
+- `hybridEncrypt` 每次调用都新生成 16 字节 DEK 与 12 字节 IV；消息字符串按 **hex** 解释（空消息传 `new Uint8Array(0)`）。
+- hybrid 同时用到 `sm2.wasm` 与 `sm4.wasm`，首次调用前请 `await Promise.all([sm2.ensureLoaded(), sm4.ensureLoaded()])`。
+- `hybridDecrypt` 支持 `{ safeMode: true }`，密文支失败返回 `null`。
+- SM2 没有国标定义的独立 KEM；`kemEncrypt` 是“用 SM2 公钥加密随机密钥”的约定做法。
+
 ### SM2 —— 密钥交换协议（GM/T 0003.3）
 
 ```ts
@@ -153,8 +177,14 @@ sm9.decrypt(encKp.masterPrivatePem, 'alice@foo.com', ct);      // → '616263'
 // 注意第一参数是**加密主私钥**（KEM 需要它派生 Ppub-e，与 encrypt 可传主公钥不同）。
 const { key, encapsulation } = sm9.kemEncrypt(encKp.masterPrivatePem, 'alice@foo.com', 32);
 sm9.kemDecrypt(encKp.masterPrivatePem, 'alice@foo.com', encapsulation, 32);  // === key
+
+// 混合加密：主公钥（或主私钥）+ id 封装 16 字节 DEK，再用 SM4-GCM 加密消息。
+const sealed = sm9.hybridEncrypt(encKp.masterPublicPem, 'alice@foo.com', '616263');
+sm9.hybridDecrypt(encKp.masterPrivatePem, 'alice@foo.com', sealed);  // → '616263'
 ```
 
+> SM9 hybrid 同时用到 `sm9.wasm` 与 `sm4.wasm`：首次调用前请分别 `await sm9.ensureLoaded()` 与 `await sm4.ensureLoaded()`。
+
 ### ZUC —— EEA3 机密性 + EIA3 完整性
 
 ```ts
@@ -179,10 +209,10 @@ zuc.zucMac(key, macIv, '616263');               // → 4 字节标签
 
 | 模块 | 函数 |
 |---|---|
-| `sm2` | `generateKeyPair`(async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `createExchangeInitiator`(async) · `createExchangeResponder`(async) |
+| `sm2` | `generateKeyPair`(async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator`(async) · `createExchangeResponder`(async) |
 | `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` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator`(async) · `createExchangeResponder`(async) |
+| `sm9` | `generateKeyPair`(async) · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator`(async) · `createExchangeResponder`(async) |
 | `zuc` | `zucKeystream` · `zucEncrypt` · `zucDecrypt` · `zucMac` · `zucEia3Iv` · `configureReuseGuard` |
 
 文档名别名（与主名指向同一实现）：`sm4.encryptCTR`/`decryptCTR` 等价 `cryptCTR`、`encryptOFB`/`decryptOFB` 等价 `cryptOFB`；`zuc.encrypt`/`decrypt`/`generateKeystream`/`mac`/`eia3` 等价 `zucEncrypt`/`zucDecrypt`/`zucKeystream`/`zucMac`。
@@ -210,6 +240,8 @@ import { encryptCBC } from 'sm-crypto-wasm/sm4';
 | 浏览器（经打包器） | `fetch(new URL('../<algo>/<algo>.wasm', import.meta.url))`，由打包器归档并重写 URL |
 | Web Worker | 加载器不依赖 DOM，Worker 内可用 |
 | Deno / Bun | 走 Node 同路径 |
+| 微信内置浏览器 | 与浏览器相同（`fetch` + `crypto.getRandomValues`）；见[微信与小程序](https://jktantan.github.io/sm-crypto-wasm/guide/wechat) |
+| 微信小程序 | `WXWebAssembly` + `wx.getRandomValues`；见[微信与小程序](https://jktantan.github.io/sm-crypto-wasm/guide/wechat) |
 
 ### 打包器支持
 
@@ -434,6 +466,32 @@ sm2.decrypt(privateKeyPem, ct, { safeMode: true });     // returns null instead
 Keys may also be passed as raw hex / `Uint8Array` (32-byte private key, 64- or
 65-byte public key).
 
+### SM2 — key encapsulation & hybrid encryption
+
+```ts
+import { sm2 } from 'sm-crypto-wasm';
+
+await sm2.ensureLoaded();
+
+// KEM: protect a random symmetric key with the public key (16 or 32 bytes).
+const { key, encapsulation } = sm2.kemEncrypt(publicKeyPem, 32);
+sm2.kemDecrypt(privateKeyPem, encapsulation, 32);       // === key
+
+// Hybrid encryption: one call performs KEM + SM4-GCM; suited to large messages.
+// Returns a versioned sealed value: version || klen || encapLen || encapsulation || iv || tag || ct
+const sealed = sm2.hybridEncrypt(publicKeyPem, '616263');
+sm2.hybridDecrypt(privateKeyPem, sealed);               // → '616263' (plaintext hex)
+
+// The sealed value can also be inspected as a self-describing object.
+const obj = sm2.sealedToObject(sealed);
+sm2.hybridDecrypt(privateKeyPem, sm2.sealedFromObject(obj));
+```
+
+- Every `hybridEncrypt` call generates a fresh 16-byte DEK and 12-byte IV; message strings are interpreted as **hex** (pass `new Uint8Array(0)` for an empty message).
+- Hybrid uses both `sm2.wasm` and `sm4.wasm`; warm them up with `await Promise.all([sm2.ensureLoaded(), sm4.ensureLoaded()])` before the first call.
+- `hybridDecrypt` supports `{ safeMode: true }`, returning `null` for ciphertext-side failures.
+- SM2 has no standardized KEM construction; `kemEncrypt` is the conventional "encrypt a random key with SM2" idiom.
+
 ### SM2 — key exchange (GM/T 0003.3)
 
 ```ts
@@ -479,8 +537,15 @@ sm9.decrypt(encKp.masterPrivatePem, 'alice@foo.com', ct);      // → '616263'
 // derive Ppub-e; encrypt() above can take a master public key instead).
 const { key, encapsulation } = sm9.kemEncrypt(encKp.masterPrivatePem, 'alice@foo.com', 32);
 sm9.kemDecrypt(encKp.masterPrivatePem, 'alice@foo.com', encapsulation, 32);  // === key
+
+// Hybrid encryption: encapsulate a 16-byte DEK with the master public (or private) key + id,
+// then encrypt the message with SM4-GCM.
+const sealed = sm9.hybridEncrypt(encKp.masterPublicPem, 'alice@foo.com', '616263');
+sm9.hybridDecrypt(encKp.masterPrivatePem, 'alice@foo.com', sealed);  // → '616263'
 ```
 
+> SM9 hybrid uses both `sm9.wasm` and `sm4.wasm`: call `await sm9.ensureLoaded()` and `await sm4.ensureLoaded()` before the first use.
+
 ### ZUC — EEA3 confidentiality + EIA3 integrity
 
 ```ts
@@ -505,10 +570,10 @@ zuc.zucMac(key, macIv, '616263');               // → 4-byte tag
 
 | Module | Functions |
 |---|---|
-| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
 | `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` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `sm9` | `generateKeyPair` (async) · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
 | `zuc` | `zucKeystream` · `zucEncrypt` · `zucDecrypt` · `zucMac` · `zucEia3Iv` · `configureReuseGuard` |
 
 Documented aliases (they point to the same implementation):
@@ -541,6 +606,8 @@ Available sub-paths: `sm-crypto-wasm/sm2` · `/sm3` · `/sm4` · `/sm9` · `/zuc
 | Browser (via a bundler) | `fetch(new URL('../<algo>/<algo>.wasm', import.meta.url))`; the bundler archives and rewrites it |
 | Web Worker | the loader is DOM-free and works inside a Worker |
 | Deno / Bun | follows the Node path |
+| WeChat built-in browser | same as browsers (`fetch` + `crypto.getRandomValues`); see [WeChat & Mini Programs](https://jktantan.github.io/sm-crypto-wasm/en/guide/wechat) |
+| WeChat Mini Program | `WXWebAssembly` + `wx.getRandomValues`; see [WeChat & Mini Programs](https://jktantan.github.io/sm-crypto-wasm/en/guide/wechat) |
 
 ### Bundler support
 
@@ -794,6 +861,32 @@ sm2.decrypt(privateKeyPem, ct, { safeMode: true });     // при ошибке
 Ключи также можно передавать как «сырой» hex или `Uint8Array` (32 байта для
 закрытого ключа, 64 или 65 байт для открытого).
 
+### SM2 — инкапсуляция ключа и гибридное шифрование
+
+```ts
+import { sm2 } from 'sm-crypto-wasm';
+
+await sm2.ensureLoaded();
+
+// KEM: защитить случайный симметричный ключ открытым ключом (16 или 32 байта).
+const { key, encapsulation } = sm2.kemEncrypt(publicKeyPem, 32);
+sm2.kemDecrypt(privateKeyPem, encapsulation, 32);       // === key
+
+// Гибридное шифрование: один вызов выполняет KEM + SM4-GCM; подходит для больших сообщений.
+// Возвращает версионированный sealed: version || klen || encapLen || encapsulation || iv || tag || ct
+const sealed = sm2.hybridEncrypt(publicKeyPem, '616263');
+sm2.hybridDecrypt(privateKeyPem, sealed);               // → '616263' (открытый текст в hex)
+
+// sealed можно представить в виде самоописывающего объекта.
+const obj = sm2.sealedToObject(sealed);
+sm2.hybridDecrypt(privateKeyPem, sm2.sealedFromObject(obj));
+```
+
+- Каждый вызов `hybridEncrypt` создаёт новые 16-байтовый DEK и 12-байтовый IV; строки сообщений интерпретируются как **hex** (для пустого сообщения передайте `new Uint8Array(0)`).
+- Гибридному режиму нужны и `sm2.wasm`, и `sm4.wasm`; перед первым вызовом выполните `await Promise.all([sm2.ensureLoaded(), sm4.ensureLoaded()])`.
+- `hybridDecrypt` поддерживает `{ safeMode: true }` и возвращает `null` при ошибках, связанных с шифртекстом.
+- В SM2 нет стандартизованной конструкции KEM; `kemEncrypt` — общепринятый приём «зашифровать случайный ключ открытым ключом SM2».
+
 ### SM2 — протокол обмена ключами (GM/T 0003.3)
 
 ```ts
@@ -839,8 +932,15 @@ sm9.decrypt(encKp.masterPrivatePem, 'alice@foo.com', ct);      // → '616263'
 // (KEM нуждается в нём, чтобы вывести Ppub-e; для encrypt выше допустим мастер-публичный ключ).
 const { key, encapsulation } = sm9.kemEncrypt(encKp.masterPrivatePem, 'alice@foo.com', 32);
 sm9.kemDecrypt(encKp.masterPrivatePem, 'alice@foo.com', encapsulation, 32);  // === key
+
+// Гибридное шифрование: инкапсулировать 16-байтовый DEK мастер-публичным (или приватным)
+// ключом и id, затем зашифровать сообщение через SM4-GCM.
+const sealed = sm9.hybridEncrypt(encKp.masterPublicPem, 'alice@foo.com', '616263');
+sm9.hybridDecrypt(encKp.masterPrivatePem, 'alice@foo.com', sealed);  // → '616263'
 ```
 
+> Гибридному режиму SM9 нужны и `sm9.wasm`, и `sm4.wasm`: перед первым вызовом выполните `await sm9.ensureLoaded()` и `await sm4.ensureLoaded()`.
+
 ### ZUC — конфиденциальность EEA3 и целостность EIA3
 
 ```ts
@@ -865,10 +965,10 @@ zuc.zucMac(key, macIv, '616263');               // → 4-байтовый тег
 
 | Модуль | Функции |
 |---|---|
-| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `sm2` | `generateKeyPair` (async) · `getPublicKey` · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
 | `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` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
+| `sm9` | `generateKeyPair` (async) · `sign` · `verify` · `encrypt` · `decrypt` · `kemEncrypt` · `kemDecrypt` · `hybridEncrypt` · `hybridDecrypt` · `sealedToObject` · `sealedFromObject` · `getSignPublicKey` · `getEncPublicKey` · `getUserPublicKey` · `createExchangeInitiator` (async) · `createExchangeResponder` (async) |
 | `zuc` | `zucKeystream` · `zucEncrypt` · `zucDecrypt` · `zucMac` · `zucEia3Iv` · `configureReuseGuard` |
 
 Документированные алиасы (указывают на ту же реализацию):
@@ -901,6 +1001,8 @@ import { encryptCBC } from 'sm-crypto-wasm/sm4';
 | Браузер (через сборщик) | `fetch(new URL('../<algo>/<algo>.wasm', import.meta.url))`; сборщик кладёт файл в вывод и переписывает URL |
 | Web Worker | загрузчик не зависит от DOM и работает внутри Worker'а |
 | Deno / Bun | идут по Node-пути |
+| Встроенный браузер WeChat | как обычный браузер (`fetch` + `crypto.getRandomValues`); см. [WeChat и мини-программы](https://jktantan.github.io/sm-crypto-wasm/ru/guide/wechat) |
+| Мини-программа WeChat | `WXWebAssembly` + `wx.getRandomValues`; см. [WeChat и мини-программы](https://jktantan.github.io/sm-crypto-wasm/ru/guide/wechat) |
 
 ### Поддержка сборщиков
 

package/dist/common/hybrid.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 混合加密的共享输入约定。
+ *
+ * 两个 hybrid 模块（SM2 / SM9）对 message 采用**同一套**字符串语义：
+ * - `Uint8Array`：原样使用（拷贝）；
+ * - `string`：必须是 hex（允许 `0x` 前缀），不再猜 base64 / UTF-8；
+ * - 空消息请传 `new Uint8Array(0)`；空字符串按既有 `toBytes` 契约直接拒绝，
+ *   避免“空输入静默成功”。
+ *
+ * IV 同样按 hex / Uint8Array 处理，未提供时由宿主 CSPRNG 生成 12 字节。
+ */
+/**
+ * 把 hybrid 的 message 归一化为字节。
+ *
+ * @param input hex 字符串或字节数组。
+ * @param label 错误信息里的字段名。
+ * @throws TypeError 空字符串、奇数长度、非 hex 字符或类型不对。
+ */
+export declare function toMessageBytes(input: string | Uint8Array, label?: string): Uint8Array;
+/**
+ * 归一化 hybrid 的 IV：未提供则新生成 12 字节；提供则必须恰好 12 字节。
+ *
+ * @throws RangeError 长度不是 12。
+ */
+export declare function resolveIv(iv: string | Uint8Array | undefined): Uint8Array;

package/dist/common/hybrid.js

@@ -0,0 +1,48 @@
+/**
+ * 混合加密的共享输入约定。
+ *
+ * 两个 hybrid 模块（SM2 / SM9）对 message 采用**同一套**字符串语义：
+ * - `Uint8Array`：原样使用（拷贝）；
+ * - `string`：必须是 hex（允许 `0x` 前缀），不再猜 base64 / UTF-8；
+ * - 空消息请传 `new Uint8Array(0)`；空字符串按既有 `toBytes` 契约直接拒绝，
+ *   避免“空输入静默成功”。
+ *
+ * IV 同样按 hex / Uint8Array 处理，未提供时由宿主 CSPRNG 生成 12 字节。
+ */
+import { hexToBytes } from '../runtime/convert.js';
+import { randomBytes } from '../runtime/random.js';
+import { SEALED_IV_LEN } from './sealed.js';
+/**
+ * 把 hybrid 的 message 归一化为字节。
+ *
+ * @param input hex 字符串或字节数组。
+ * @param label 错误信息里的字段名。
+ * @throws TypeError 空字符串、奇数长度、非 hex 字符或类型不对。
+ */
+export function toMessageBytes(input, label = 'message') {
+    if (input instanceof Uint8Array)
+        return new Uint8Array(input);
+    if (typeof input !== 'string') {
+        throw new TypeError(`hybrid: ${label} 必须是 hex 字符串或 Uint8Array`);
+    }
+    if (input.length === 0) {
+        throw new TypeError(`hybrid: ${label} 为空；空消息请传 new Uint8Array(0)`);
+    }
+    return hexToBytes(input, label);
+}
+/**
+ * 归一化 hybrid 的 IV：未提供则新生成 12 字节；提供则必须恰好 12 字节。
+ *
+ * @throws RangeError 长度不是 12。
+ */
+export function resolveIv(iv) {
+    const out = iv === undefined
+        ? randomBytes(SEALED_IV_LEN)
+        : iv instanceof Uint8Array
+            ? new Uint8Array(iv)
+            : hexToBytes(iv, 'iv');
+    if (out.length !== SEALED_IV_LEN) {
+        throw new RangeError(`hybrid: iv 必须是 ${SEALED_IV_LEN} 字节，实际 ${out.length}`);
+    }
+    return out;
+}

package/dist/common/sealed.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 混合加密密文（sealed）的版本化序列化。
+ *
+ * 布局（全部大端）：
+ *
+ * ```text
+ *   version(1) || klen(1) || encapLen(2) || encapsulation(encapLen)
+ *              || iv(12) || tag(16) || ct(rest)
+ * ```
+ *
+ * - `version` 当前为 `1`；未知版本必须拒绝，不能静默按 v1 解析。
+ * - `klen` 是 KEM 输出的 DEM 密钥字节数（SM4-128 固定为 16）。
+ * - `encapLen` 让解析器能精确切出 KEM 封装段，同时也能识别“长度字段说谎”。
+ * - `iv` / `tag` 定长：GCM 推荐 12 字节 IV、16 字节 tag。
+ *
+ * 对象形态 `SealedObject` 只用于调试 / 自描述场景；线上传输仍建议用单个
+ * hex 字符串（`sealedToObject` / `sealedFromObject` 负责互转）。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 2。
+ */
+/** 当前 sealed 格式版本。 */
+export declare const SEALED_VERSION = 1;
+/** GCM IV 长度（字节）。 */
+export declare const SEALED_IV_LEN = 12;
+/** GCM tag 长度（字节）。 */
+export declare const SEALED_TAG_LEN = 16;
+/** 头部长度：version + klen + encapLen。 */
+export declare const SEALED_HEADER_LEN = 4;
+/** DEM 密钥长度：SM4-128 固定 16 字节。 */
+export declare const DEM_KEY_LEN = 16;
+/** 解析后的 sealed 各段（字节形态）。 */
+export interface SealedParts {
+    version: number;
+    klen: number;
+    encapsulation: Uint8Array;
+    iv: Uint8Array;
+    tag: Uint8Array;
+    ct: Uint8Array;
+}
+/**
+ * sealed 的对象形态（各字段均为 hex）。
+ *
+ * 适合日志 / 调试 / 与手工 `kemEncrypt + sm4.encryptGCM` 组装互操作。
+ */
+export interface SealedObject {
+    /** 格式版本，当前必须为 1。 */
+    v: number;
+    /** KEM 输出的 DEM 密钥字节数。 */
+    klen: number;
+    /** KEM 封装段。 */
+    encapsulation: string;
+    /** GCM IV（12 字节）。 */
+    iv: string;
+    /** GCM tag（16 字节）。 */
+    tag: string;
+    /** GCM 密文（可为空）。 */
+    ct: string;
+}
+/** 把各段组装成 sealed 字节。 */
+export declare function encodeSealed(parts: SealedParts): Uint8Array;
+/**
+ * 严格解析 sealed 字节。
+ *
+ * @throws {InvalidCiphertextError} 版本未知、长度字段与实长不符、任何一段被截断。
+ */
+export declare function decodeSealed(sealed: string | Uint8Array): SealedParts;
+/** sealed → 对象形态（各字段 hex）。 */
+export declare function sealedToObject(sealed: string | Uint8Array): SealedObject;
+/**
+ * 对象形态 → sealed hex。
+ *
+ * 严格校验每个字段：版本、klen、encapsulation 非空、iv/tag 定长。
+ * 任何不合法都抛 `InvalidCiphertextError`（对象本身描述的是密文）。
+ */
+export declare function sealedFromObject(obj: SealedObject): string;

package/dist/common/sealed.js

@@ -0,0 +1,160 @@
+/**
+ * 混合加密密文（sealed）的版本化序列化。
+ *
+ * 布局（全部大端）：
+ *
+ * ```text
+ *   version(1) || klen(1) || encapLen(2) || encapsulation(encapLen)
+ *              || iv(12) || tag(16) || ct(rest)
+ * ```
+ *
+ * - `version` 当前为 `1`；未知版本必须拒绝，不能静默按 v1 解析。
+ * - `klen` 是 KEM 输出的 DEM 密钥字节数（SM4-128 固定为 16）。
+ * - `encapLen` 让解析器能精确切出 KEM 封装段，同时也能识别“长度字段说谎”。
+ * - `iv` / `tag` 定长：GCM 推荐 12 字节 IV、16 字节 tag。
+ *
+ * 对象形态 `SealedObject` 只用于调试 / 自描述场景；线上传输仍建议用单个
+ * hex 字符串（`sealedToObject` / `sealedFromObject` 负责互转）。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 2。
+ */
+import { bytesToHex, hexToBytes, toBytes } from '../runtime/convert.js';
+import { InvalidCiphertextError } from '../runtime/errors.js';
+/** 当前 sealed 格式版本。 */
+export const SEALED_VERSION = 1;
+/** GCM IV 长度（字节）。 */
+export const SEALED_IV_LEN = 12;
+/** GCM tag 长度（字节）。 */
+export const SEALED_TAG_LEN = 16;
+/** 头部长度：version + klen + encapLen。 */
+export const SEALED_HEADER_LEN = 4;
+/** DEM 密钥长度：SM4-128 固定 16 字节。 */
+export const DEM_KEY_LEN = 16;
+/** 把各段组装成 sealed 字节。 */
+export function encodeSealed(parts) {
+    const { version, klen, encapsulation, iv, tag, ct } = parts;
+    if (!Number.isInteger(version) || version < 0 || version > 0xff) {
+        throw new RangeError(`sealed: version 必须是 [0, 255] 内的整数，实际 ${version}`);
+    }
+    if (!Number.isInteger(klen) || klen <= 0 || klen > 0xff) {
+        throw new RangeError(`sealed: klen 必须是 [1, 255] 内的整数，实际 ${klen}`);
+    }
+    if (encapsulation.length > 0xffff) {
+        throw new RangeError(`sealed: encapsulation 不能超过 65535 字节，实际 ${encapsulation.length}`);
+    }
+    if (iv.length !== SEALED_IV_LEN) {
+        throw new RangeError(`sealed: iv 必须是 ${SEALED_IV_LEN} 字节，实际 ${iv.length}`);
+    }
+    if (tag.length !== SEALED_TAG_LEN) {
+        throw new RangeError(`sealed: tag 必须是 ${SEALED_TAG_LEN} 字节，实际 ${tag.length}`);
+    }
+    const out = new Uint8Array(SEALED_HEADER_LEN + encapsulation.length + SEALED_IV_LEN + SEALED_TAG_LEN + ct.length);
+    out[0] = version;
+    out[1] = klen;
+    out[2] = (encapsulation.length >>> 8) & 0xff;
+    out[3] = encapsulation.length & 0xff;
+    let off = SEALED_HEADER_LEN;
+    out.set(encapsulation, off);
+    off += encapsulation.length;
+    out.set(iv, off);
+    off += SEALED_IV_LEN;
+    out.set(tag, off);
+    off += SEALED_TAG_LEN;
+    out.set(ct, off);
+    return out;
+}
+/** 把输入归一化成 sealed 字节。空输入按密文支错误处理。 */
+function sealedBytes(sealed) {
+    if (typeof sealed === 'string' && sealed.length === 0) {
+        throw new InvalidCiphertextError('sealed: 密文为空');
+    }
+    if (sealed instanceof Uint8Array && sealed.length === 0) {
+        throw new InvalidCiphertextError('sealed: 密文为空');
+    }
+    return toBytes(sealed, 'sealed');
+}
+/**
+ * 严格解析 sealed 字节。
+ *
+ * @throws {InvalidCiphertextError} 版本未知、长度字段与实长不符、任何一段被截断。
+ */
+export function decodeSealed(sealed) {
+    const b = sealedBytes(sealed);
+    if (b.length < SEALED_HEADER_LEN) {
+        throw new InvalidCiphertextError(`sealed: 长度不足（${b.length} 字节，至少需要 4 字节头部）`);
+    }
+    const version = b[0] ?? 0;
+    if (version !== SEALED_VERSION) {
+        throw new InvalidCiphertextError(`sealed: 未知版本 ${version}（当前支持 ${SEALED_VERSION}）`);
+    }
+    const klen = b[1] ?? 0;
+    if (klen === 0) {
+        throw new InvalidCiphertextError('sealed: klen 不能为 0');
+    }
+    const encapLen = ((b[2] ?? 0) << 8) | (b[3] ?? 0);
+    const fixed = SEALED_HEADER_LEN + encapLen + SEALED_IV_LEN + SEALED_TAG_LEN;
+    if (b.length < fixed) {
+        throw new InvalidCiphertextError(`sealed: 长度字段 encapLen=${encapLen} 与实长 ${b.length} 不符（至少需要 ${fixed} 字节）`);
+    }
+    let off = SEALED_HEADER_LEN;
+    const encapsulation = b.slice(off, off + encapLen);
+    off += encapLen;
+    const iv = b.slice(off, off + SEALED_IV_LEN);
+    off += SEALED_IV_LEN;
+    const tag = b.slice(off, off + SEALED_TAG_LEN);
+    off += SEALED_TAG_LEN;
+    const ct = b.slice(off);
+    return { version, klen, encapsulation, iv, tag, ct };
+}
+/** sealed → 对象形态（各字段 hex）。 */
+export function sealedToObject(sealed) {
+    const p = decodeSealed(sealed);
+    return {
+        v: p.version,
+        klen: p.klen,
+        encapsulation: bytesToHex(p.encapsulation),
+        iv: bytesToHex(p.iv),
+        tag: bytesToHex(p.tag),
+        ct: bytesToHex(p.ct),
+    };
+}
+/**
+ * 对象形态 → sealed hex。
+ *
+ * 严格校验每个字段：版本、klen、encapsulation 非空、iv/tag 定长。
+ * 任何不合法都抛 `InvalidCiphertextError`（对象本身描述的是密文）。
+ */
+export function sealedFromObject(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        throw new InvalidCiphertextError('sealed: 对象形态必须是 { v, klen, encapsulation, iv, tag, ct }');
+    }
+    if (typeof obj.v !== 'number' ||
+        typeof obj.klen !== 'number' ||
+        typeof obj.encapsulation !== 'string' ||
+        typeof obj.iv !== 'string' ||
+        typeof obj.tag !== 'string' ||
+        typeof obj.ct !== 'string') {
+        throw new InvalidCiphertextError('sealed: 对象字段类型必须是 { v:number, klen:number, encapsulation/iv/tag/ct:string }');
+    }
+    if (obj.v !== SEALED_VERSION) {
+        throw new InvalidCiphertextError(`sealed: 未知版本 ${String(obj.v)}（当前支持 ${SEALED_VERSION}）`);
+    }
+    if (!Number.isInteger(obj.klen) || obj.klen <= 0 || obj.klen > 0xff) {
+        throw new InvalidCiphertextError(`sealed: klen 必须是 [1, 255] 内的整数，实际 ${String(obj.klen)}`);
+    }
+    const encapsulation = hexToBytes(obj.encapsulation, 'encapsulation');
+    const iv = hexToBytes(obj.iv, 'iv');
+    const tag = hexToBytes(obj.tag, 'tag');
+    const ct = obj.ct.length === 0 ? new Uint8Array(0) : hexToBytes(obj.ct, 'ct');
+    if (encapsulation.length === 0) {
+        throw new InvalidCiphertextError('sealed: encapsulation 不能为空');
+    }
+    if (iv.length !== SEALED_IV_LEN) {
+        throw new InvalidCiphertextError(`sealed: iv 必须是 ${SEALED_IV_LEN} 字节，实际 ${iv.length}`);
+    }
+    if (tag.length !== SEALED_TAG_LEN) {
+        throw new InvalidCiphertextError(`sealed: tag 必须是 ${SEALED_TAG_LEN} 字节，实际 ${tag.length}`);
+    }
+    return bytesToHex(encodeSealed({ version: obj.v, klen: obj.klen, encapsulation, iv, tag, ct }));
+}

package/dist/runtime/base64.core.d.ts

@@ -0,0 +1,22 @@
+/**
+ * base64 纯 JS 实现（宿主既没有 `Buffer`、也没有 `btoa` / `atob` 时的兜底）。
+ *
+ * 存在理由：微信小程序等运行时没有 `btoa` / `atob`，而 SM2 / SM9 的 PEM 密钥
+ * 生成与解析需要 base64。base64 是确定性编码、不属于密码学原语，因此在库内兜底
+ * 不需要像 RNG 那样 fail-closed。
+ *
+ * 只在 `runtime/convert.ts` 的最后一级回退里使用；Node 有 `Buffer`、浏览器有
+ * `btoa` / `atob` 时都不会走到这里。零 `node:*` 引用，可安全进入浏览器/小程序产物。
+ */
+/** 标准 base64 编码（带 `=` padding）。 */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * 标准 base64 解码。
+ *
+ * 与 `atob` 的宽松度对齐：允许空白字符与缺失 padding；非法字符、非法长度抛
+ * `TypeError`（`convert.base64ToBytes` 的契约是失败抛 TypeError）。
+ *
+ * @param b64 base64 字符串。
+ * @param label 错误信息里的字段名。
+ */
+export declare function decodeBase64(b64: string, label?: string): Uint8Array;

package/dist/runtime/base64.core.js

@@ -0,0 +1,68 @@
+/**
+ * base64 纯 JS 实现（宿主既没有 `Buffer`、也没有 `btoa` / `atob` 时的兜底）。
+ *
+ * 存在理由：微信小程序等运行时没有 `btoa` / `atob`，而 SM2 / SM9 的 PEM 密钥
+ * 生成与解析需要 base64。base64 是确定性编码、不属于密码学原语，因此在库内兜底
+ * 不需要像 RNG 那样 fail-closed。
+ *
+ * 只在 `runtime/convert.ts` 的最后一级回退里使用；Node 有 `Buffer`、浏览器有
+ * `btoa` / `atob` 时都不会走到这里。零 `node:*` 引用，可安全进入浏览器/小程序产物。
+ */
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** 标准 base64 编码（带 `=` padding）。 */
+export function encodeBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i] ?? 0;
+        const hasB = i + 1 < bytes.length;
+        const hasC = i + 2 < bytes.length;
+        const b = hasB ? (bytes[i + 1] ?? 0) : 0;
+        const c = hasC ? (bytes[i + 2] ?? 0) : 0;
+        const n = (a << 16) | (b << 8) | c;
+        out += B64.charAt((n >> 18) & 63);
+        out += B64.charAt((n >> 12) & 63);
+        out += hasB ? B64.charAt((n >> 6) & 63) : '=';
+        out += hasC ? B64.charAt(n & 63) : '=';
+    }
+    return out;
+}
+/**
+ * 标准 base64 解码。
+ *
+ * 与 `atob` 的宽松度对齐：允许空白字符与缺失 padding；非法字符、非法长度抛
+ * `TypeError`（`convert.base64ToBytes` 的契约是失败抛 TypeError）。
+ *
+ * @param b64 base64 字符串。
+ * @param label 错误信息里的字段名。
+ */
+export function decodeBase64(b64, label = 'base64') {
+    const stripped = b64.replace(/[\t\n\f\r ]/g, '');
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(stripped)) {
+        throw new TypeError(`${label}: invalid base64`);
+    }
+    const pad = stripped.endsWith('==') ? 2 : stripped.endsWith('=') ? 1 : 0;
+    if (pad > 0 && stripped.length % 4 !== 0) {
+        throw new TypeError(`${label}: invalid base64 padding`);
+    }
+    const body = pad > 0 ? stripped.slice(0, -pad) : stripped;
+    if (body.length % 4 === 1) {
+        throw new TypeError(`${label}: invalid base64 length`);
+    }
+    const out = new Uint8Array(Math.floor((body.length * 3) / 4));
+    let buffer = 0;
+    let bits = 0;
+    let pos = 0;
+    for (let i = 0; i < body.length; i++) {
+        const v = B64.indexOf(body.charAt(i));
+        if (v < 0)
+            throw new TypeError(`${label}: invalid base64 character at index ${i}`);
+        buffer = (buffer << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[pos++] = (buffer >> bits) & 0xff;
+            buffer &= (1 << bits) - 1;
+        }
+    }
+    return out.subarray(0, pos);
+}

package/dist/runtime/convert.d.ts

@@ -40,10 +40,19 @@ export declare function fromBytes(bytes: Uint8Array, format?: OutputFormat): str
 export declare function bytesToHex(bytes: Uint8Array): string;
 /** hex 字符串 → bytes。支持 `0x` 前缀。奇数位长度或非法字符抛错。 */
 export declare function hexToBytes(hex: string, label?: string): Uint8Array;
-/** bytes → base64。Node `Buffer` 优先，浏览器回落到 `btoa`。 */
+/**
+ * bytes → base64。优先级：Node `Buffer` → 宿主 `btoa` → 纯 JS 兜底。
+ *
+ * 微信小程序既没有 `Buffer` 也没有 `btoa`，会走最后一级；不需要宿主再安装
+ * base64 polyfill。
+ */
 export declare function bytesToBase64(bytes: Uint8Array): string;
-/** base64 字符串 → bytes。失败抛 TypeError。 */
-export declare function base64ToBytes(b64: string, _label?: string): Uint8Array;
+/**
+ * base64 字符串 → bytes。失败抛 TypeError。
+ *
+ * 优先级：Node `Buffer` → 宿主 `atob` → 纯 JS 兜底（微信小程序等）。
+ */
+export declare function base64ToBytes(b64: string, label?: string): Uint8Array;
 /** PEM → bytes。剥去 BEGIN/END armor，base64 解码。 */
 export declare function pemToBytes(pem: string, label?: string): Uint8Array;
 /** bytes → PEM（带 BEGIN/END 头）。`kind` 例：`SM2 PRIVATE KEY`。 */