sm-crypto-wasm 0.2.1 → 0.3.0

package/dist/sm2/index.js

@@ -7,6 +7,8 @@
  * - `verify(publicKey, message, signature)`：验签
  * - `encrypt(publicKey, message, options?)`：加密（默认 C1C3C2）
  * - `decrypt(privateKey, ciphertext)`：解密
+ * - `kemEncrypt` / `kemDecrypt`：KEM（用公钥保护随机对称密钥，见 `./kem.ts`）
+ * - `hybridEncrypt` / `hybridDecrypt`：KEM + SM4-GCM 混合加密（见 `./hybrid.ts`）
  *
  * 说明：
  * - 密钥输入同时接受裸字节（hex）与 PEM（PKCS#8/SEC1 私钥、SPKI 公钥）。
@@ -478,3 +480,6 @@ function decryptRaw(d, ct) {
 // SM2 密钥交换协议（GM/T 0003.3-2014）：createExchangeInitiator /
 // createExchangeResponder 由 `./exchange` 提供，在此并入 sm2 命名空间。
 export * from './exchange.js';
+// SM2 KEM（用公钥保护随机对称密钥）与混合加密（KEM + SM4-GCM）。
+export * from './hybrid.js';
+export * from './kem.js';

package/dist/sm2/kem.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SM2 密钥封装（KEM）—— 用 SM2 公钥保护一把随机对称密钥。
+ *
+ * **注意：这不是国标定义的“SM2-KEM”。** GM/T 0003 只定义了 SM2 公钥加密，
+ * 没有定义独立的 KEM 构造；本模块是业界约定俗成的做法：
+ *
+ *   key           = 宿主 CSPRNG 生成的 `klen` 字节对称密钥
+ *   encapsulation = SM2 加密(key)（完整 C1C3C2 密文，自带 C3 完整性校验）
+ *
+ * 接收方用 `kemDecrypt` 解出同一把 key。它的安全性完全继承自 SM2 公钥加密：
+ * - 每次封装都取新的随机数 `k`（由 `sm2.encrypt` 内部完成）；
+ * - encapsulation 被篡改时 C3 校验失败，抛 `DecryptionError`；
+ * - 错误私钥同样过不了 C3 校验，不会返回垃圾密钥。
+ *
+ * 若需要“公钥只保护短密钥、数据交给对称算法”的完整用法，直接用
+ * `hybridEncrypt` / `hybridDecrypt`（本模块的 KEM + SM4-GCM 组装）。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 1。
+ */
+/** KEM 封装结果。 */
+export interface Sm2KemResult {
+    /** 会话密钥（hex，`2*klen` 个字符）。 */
+    key: string;
+    /** SM2 密文（C1C3C2 hex，长度 `97 + klen` 字节）。 */
+    encapsulation: string;
+}
+/** `kemDecrypt` 选项。 */
+export interface Sm2KemDecryptOptions {
+    /**
+     * 解封装失败时返回 `null` 而不抛错。
+     *
+     * 只覆盖密文支错误（`CiphertextError`：密文结构错 / C3 校验失败）；
+     * 参数类型错误（`TypeError` / `RangeError`）仍会抛出。
+     */
+    safeMode?: boolean;
+}
+/**
+ * SM2 密钥封装：生成一把随机会话密钥，并用接收方公钥封装。
+ *
+ * @param publicKey 64 或 65 字节公钥（hex / Uint8Array / PEM）。
+ * @param klen 会话密钥字节长度，默认 32。
+ * @returns `{ key, encapsulation }`，均为 hex。
+ */
+export declare function kemEncrypt(publicKey: string | Uint8Array, klen?: number): Sm2KemResult;
+/**
+ * SM2 密钥解封装：从 encapsulation 恢复会话密钥。
+ *
+ * @param privateKey 32 字节私钥（hex / Uint8Array / PEM）。
+ * @param encapsulation `kemEncrypt` 产出的 SM2 密文。
+ * @param klen 会话密钥字节长度，默认 32；必须与封装时一致。
+ * @returns 会话密钥 hex。
+ * @throws {DecryptionError} C3 校验失败、私钥错误，或解出的长度与 `klen` 不符。
+ */
+export declare function kemDecrypt(privateKey: string | Uint8Array, encapsulation: string | Uint8Array, klen: number, opts: Sm2KemDecryptOptions & {
+    safeMode: true;
+}): string | null;
+export declare function kemDecrypt(privateKey: string | Uint8Array, encapsulation: string | Uint8Array, klen?: number, opts?: Sm2KemDecryptOptions): string;

package/dist/sm2/kem.js

@@ -0,0 +1,59 @@
+/**
+ * SM2 密钥封装（KEM）—— 用 SM2 公钥保护一把随机对称密钥。
+ *
+ * **注意：这不是国标定义的“SM2-KEM”。** GM/T 0003 只定义了 SM2 公钥加密，
+ * 没有定义独立的 KEM 构造；本模块是业界约定俗成的做法：
+ *
+ *   key           = 宿主 CSPRNG 生成的 `klen` 字节对称密钥
+ *   encapsulation = SM2 加密(key)（完整 C1C3C2 密文，自带 C3 完整性校验）
+ *
+ * 接收方用 `kemDecrypt` 解出同一把 key。它的安全性完全继承自 SM2 公钥加密：
+ * - 每次封装都取新的随机数 `k`（由 `sm2.encrypt` 内部完成）；
+ * - encapsulation 被篡改时 C3 校验失败，抛 `DecryptionError`；
+ * - 错误私钥同样过不了 C3 校验，不会返回垃圾密钥。
+ *
+ * 若需要“公钥只保护短密钥、数据交给对称算法”的完整用法，直接用
+ * `hybridEncrypt` / `hybridDecrypt`（本模块的 KEM + SM4-GCM 组装）。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 1。
+ */
+import { bytesToHex } from '../runtime/convert.js';
+import { CiphertextError, DecryptionError } from '../runtime/errors.js';
+import { randomBytes } from '../runtime/random.js';
+import { decrypt, encrypt } from './index.js';
+/** `klen` 必须是正整数，且不超过宿主 CSPRNG 单次取数上限（65536）。 */
+function requireKlen(klen) {
+    if (!Number.isInteger(klen) || klen <= 0 || klen > 65_536) {
+        throw new RangeError(`sm2.kemEncrypt: klen 必须是 [1, 65536] 内的整数，实际 ${klen}`);
+    }
+}
+/**
+ * SM2 密钥封装：生成一把随机会话密钥，并用接收方公钥封装。
+ *
+ * @param publicKey 64 或 65 字节公钥（hex / Uint8Array / PEM）。
+ * @param klen 会话密钥字节长度，默认 32。
+ * @returns `{ key, encapsulation }`，均为 hex。
+ */
+export function kemEncrypt(publicKey, klen = 32) {
+    requireKlen(klen);
+    const key = randomBytes(klen);
+    const encapsulation = encrypt(publicKey, key);
+    return { key: bytesToHex(key), encapsulation };
+}
+export function kemDecrypt(privateKey, encapsulation, klen = 32, opts = {}) {
+    requireKlen(klen);
+    try {
+        const key = decrypt(privateKey, encapsulation);
+        if (key.length !== klen * 2) {
+            // C3 已通过，说明私钥正确；长度不符通常是调用方把 klen 传错了。
+            throw new DecryptionError(`sm2.kemDecrypt: 解出的密钥长度为 ${key.length / 2} 字节，与 klen=${klen} 不符`);
+        }
+        return key;
+    }
+    catch (err) {
+        if (opts.safeMode && err instanceof CiphertextError)
+            return null;
+        throw err;
+    }
+}

package/dist/sm9/core.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SM9 WASM 模块的共享访问层。
+ *
+ * 把 `ensureLoaded` / `getModule` / 内存视图从业务 API 中拆出来，供
+ * `index.ts`、`kem.ts`、`hybrid.ts` 共用，避免模块间循环依赖。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`。
+ */
+/** SM9 曲线阶 n。 */
+export declare const N: bigint;
+/** WASM 导出的最小子集。诊断入口的子集。 */
+export interface Sm9Exports extends WebAssembly.Exports {
+    readonly alloc: (n: number) => number;
+    readonly freeAll: () => void;
+    readonly signPubOut: (ksPtr: number, outPtr: number) => void;
+    readonly encPubOut: (kePtr: number, outPtr: number) => void;
+    readonly signDsOut: (ksPtr: number, idPtr: number, idLen: number, outPtr: number) => void;
+    readonly encDeOut: (kePtr: number, idPtr: number, idLen: number, outPtr: number) => void;
+    readonly sm9VerifyPubOut: (pubPtr: number, idPtr: number, idLen: number, msgPtr: number, msgLen: number, sigPtr: number) => number;
+    readonly sm9EncryptPubOut: (pubPtr: number, idPtr: number, idLen: number, msgPtr: number, msgLen: number, rPtr: number, outPtr: number, outCap: number) => number;
+    readonly sm9UserEncPubOut: (pubPtr: number, idPtr: number, idLen: number, outPtr: number) => void;
+    readonly sm9UserSignPubOut: (pubPtr: number, idPtr: number, idLen: number, outPtr: number) => void;
+    readonly sm9SignOut: (ksPtr: number, idPtr: number, idLen: number, msgPtr: number, msgLen: number, rPtr: number, outPtr: number) => void;
+    readonly sm9VerifyOut: (ksPtr: number, idPtr: number, idLen: number, msgPtr: number, msgLen: number, sigPtr: number) => number;
+    readonly sm9EncryptOut: (kePtr: number, idPtr: number, idLen: number, msgPtr: number, msgLen: number, rPtr: number, outPtr: number, outCap: number) => number;
+    readonly sm9DecryptOut: (kePtr: number, idPtr: number, idLen: number, ctPtr: number, ctLen: number, outPtr: number) => number;
+    readonly sm9KemEncryptOut: (kePtr: number, idPtr: number, idLen: number, rPtr: number, klen: number, c1Ptr: number, kPtr: number) => number;
+    /** 用加密主公钥（G1 仿射 64B）做 KEM 封装。 */
+    readonly sm9KemEncryptPubOut: (pubPtr: number, idPtr: number, idLen: number, rPtr: number, klen: number, c1Ptr: number, kPtr: number) => number;
+    readonly sm9KemDecryptOut: (kePtr: number, idPtr: number, idLen: number, c1Ptr: number, klen: number, kPtr: number) => number;
+    readonly sm9ExchEphemeralOut: (kePtr: number, peerIdPtr: number, peerIdLen: number, rPtr: number, outPtr: number) => void;
+    readonly sm9ExchKeyOut: (kePtr: number, isInitiator: number, selfIdPtr: number, selfIdLen: number, peerIdPtr: number, peerIdLen: number, rPtr: number, selfRPtr: number, peerRPtr: number, klen: number, outPtr: number) => number;
+    readonly sm9ExchConfirmOut: (kePtr: number, isInitiator: number, selfIdPtr: number, selfIdLen: number, peerIdPtr: number, peerIdLen: number, rPtr: number, selfRPtr: number, peerRPtr: number, prefix: number, outPtr: number) => void;
+    readonly sm9ExchAllOut: (kePtr: number, isInitiator: number, selfIdPtr: number, selfIdLen: number, peerIdPtr: number, peerIdLen: number, rPtr: number, selfRPtr: number, peerRPtr: number, klen: number, saPtr: number, sbPtr: number, kPtr: number) => number;
+    /** 诊断：cyclotomic 平方自测（随机子群元素上 cyc 平方 vs 通用平方）。1=一致。 */
+    readonly sqrCycSelfTestOut: (seed: number) => number;
+    readonly memory: WebAssembly.Memory;
+}
+export interface Sm9Module {
+    exports: Sm9Exports;
+    memory: WebAssembly.Memory;
+}
+/** 预热 WASM 模块。 */
+export declare function ensureLoaded(): Promise<void>;
+/** 取已加载的模块；未预热时抛错（调用方应先 `await ensureLoaded()`）。 */
+export declare function getModule(): Sm9Module;
+/** WASM 线性内存视图（每次现取，避免 memory.grow 后旧视图失效）。 */
+export declare function mem(): Uint8Array;

package/dist/sm9/core.js

@@ -0,0 +1,32 @@
+/**
+ * SM9 WASM 模块的共享访问层。
+ *
+ * 把 `ensureLoaded` / `getModule` / 内存视图从业务 API 中拆出来，供
+ * `index.ts`、`kem.ts`、`hybrid.ts` 共用，避免模块间循环依赖。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`。
+ */
+import { loadWasm } from '../runtime/loadWasm.js';
+/** SM9 曲线阶 n。 */
+export const N = BigInt('0xb640000002a3a6f1d603ab4ff58ec74449f2934b18ea8beee56ee19cd69ecf25');
+/** 预热 WASM 模块。 */
+export async function ensureLoaded() {
+    if (globalThis.__sm9Wasm)
+        return;
+    const mod = await loadWasm('sm9');
+    globalThis.__sm9Wasm = {
+        exports: mod.exports,
+        memory: mod.memory,
+    };
+}
+/** 取已加载的模块；未预热时抛错（调用方应先 `await ensureLoaded()`）。 */
+export function getModule() {
+    const m = globalThis.__sm9Wasm;
+    if (!m)
+        throw new Error('sm9: 未初始化，请先 `await ensureLoaded()`。');
+    return m;
+}
+/** WASM 线性内存视图（每次现取，避免 memory.grow 后旧视图失效）。 */
+export function mem() {
+    return new Uint8Array(getModule().memory.buffer);
+}

package/dist/sm9/hybrid.d.ts

@@ -0,0 +1,69 @@
+/**
+ * SM9 混合加密（KEM + DEM）：主公钥只保护一把短密钥，消息交给 SM4-GCM。
+ *
+ * 流程：
+ * ```
+ *   { key, encapsulation } = KEM(masterPublicKey 或 masterPrivateKey, id, 16)
+ *   { ct, tag }            = SM4-GCM(key, iv, msg, aad = encapsulation)
+ *   sealed                 = version || klen || encapLen || encapsulation
+ *                            || iv || tag || ct
+ * ```
+ *
+ * 与 `sm9.encrypt` 一致，第一参数既接受**加密主公钥**（64 字节 / SPKI PEM），
+ * 也接受**加密主私钥**（32 字节 / PKCS#8 PEM）；前者是发送方的典型形态。
+ *
+ * 本模块同时用到 `sm9.wasm` 与 `sm4.wasm`：首次调用前请分别
+ * `await sm9.ensureLoaded()` 与 `await sm4.ensureLoaded()`。
+ *
+ * 完整性边界：SM9 KEM 的 encapsulation 只有 C1（65 字节），本身没有 C3/HMAC；
+ * 错误 id / 错误主公钥会得到不同的 K，最终由 GCM tag 认证失败暴露。因此
+ * `hybridDecrypt` 对错误 id 抛的是 GCM 的 `DecryptionError`，而不是 KEM 错误。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 4。
+ */
+import { sealedFromObject, sealedToObject } from '../common/sealed.js';
+export { sealedFromObject, sealedToObject };
+/** `hybridEncrypt` 选项。 */
+export interface Sm9HybridEncryptOptions {
+    /**
+     * 显式指定 GCM IV（12 字节 hex / Uint8Array）。
+     *
+     * 默认由宿主 CSPRNG 生成。**显式复用同一个 IV 配不同消息会破坏 GCM 的机密性**，
+     * 该参数只用于测试 / 协议互操作；正常调用不要传。
+     */
+    iv?: string | Uint8Array;
+}
+/** `hybridDecrypt` 选项。 */
+export interface Sm9HybridDecryptOptions {
+    /**
+     * 解密失败时返回 `null` 而不抛错。
+     *
+     * 只覆盖密文支错误（`CiphertextError`：sealed 结构错、GCM tag 校验失败）；
+     * 参数类型错误 / 密钥格式错误仍会抛出。
+     */
+    safeMode?: boolean;
+}
+/**
+ * SM9 混合加密。
+ *
+ * @param key 加密主公钥（64 字节 / SPKI PEM）或加密主私钥（32 字节 / PKCS#8 PEM）。
+ * @param id 接收方标识。
+ * @param message 明文（hex / Uint8Array；空消息传 `new Uint8Array(0)`）。
+ * @param opts `iv` 可选，默认随机 12 字节。
+ * @returns sealed hex（版本化，与 SM2 hybrid 同一布局）。
+ */
+export declare function hybridEncrypt(key: string | Uint8Array, id: string | Uint8Array, message: string | Uint8Array, opts?: Sm9HybridEncryptOptions): string;
+/**
+ * SM9 混合解密。
+ *
+ * @param ke 加密主私钥（32 字节 / PKCS#8 PEM）。
+ * @param id 接收方标识；必须与封装时一致。
+ * @param sealed `hybridEncrypt` 的返回值。
+ * @param opts `safeMode`：失败时返回 `null`。
+ * @returns 明文 hex。
+ */
+export declare function hybridDecrypt(ke: string | Uint8Array, id: string | Uint8Array, sealed: string | Uint8Array, opts: Sm9HybridDecryptOptions & {
+    safeMode: true;
+}): string | null;
+export declare function hybridDecrypt(ke: string | Uint8Array, id: string | Uint8Array, sealed: string | Uint8Array, opts?: Sm9HybridDecryptOptions): string;

package/dist/sm9/hybrid.js

@@ -0,0 +1,80 @@
+/**
+ * SM9 混合加密（KEM + DEM）：主公钥只保护一把短密钥，消息交给 SM4-GCM。
+ *
+ * 流程：
+ * ```
+ *   { key, encapsulation } = KEM(masterPublicKey 或 masterPrivateKey, id, 16)
+ *   { ct, tag }            = SM4-GCM(key, iv, msg, aad = encapsulation)
+ *   sealed                 = version || klen || encapLen || encapsulation
+ *                            || iv || tag || ct
+ * ```
+ *
+ * 与 `sm9.encrypt` 一致，第一参数既接受**加密主公钥**（64 字节 / SPKI PEM），
+ * 也接受**加密主私钥**（32 字节 / PKCS#8 PEM）；前者是发送方的典型形态。
+ *
+ * 本模块同时用到 `sm9.wasm` 与 `sm4.wasm`：首次调用前请分别
+ * `await sm9.ensureLoaded()` 与 `await sm4.ensureLoaded()`。
+ *
+ * 完整性边界：SM9 KEM 的 encapsulation 只有 C1（65 字节），本身没有 C3/HMAC；
+ * 错误 id / 错误主公钥会得到不同的 K，最终由 GCM tag 认证失败暴露。因此
+ * `hybridDecrypt` 对错误 id 抛的是 GCM 的 `DecryptionError`，而不是 KEM 错误。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 4。
+ */
+import { resolveIv, toMessageBytes } from '../common/hybrid.js';
+import { DEM_KEY_LEN, decodeSealed, encodeSealed, SEALED_VERSION, sealedFromObject, sealedToObject, } from '../common/sealed.js';
+import { bytesToHex, hexToBytes } from '../runtime/convert.js';
+import { CiphertextError, InvalidCiphertextError } from '../runtime/errors.js';
+import { decryptGCM, encryptGCM } from '../sm4/index.js';
+import { keyArg, toBytes } from './input.js';
+import { kemDecrypt, kemEncapsulateWithMasterPublic, kemEncrypt } from './kem.js';
+export { sealedFromObject, sealedToObject };
+/**
+ * SM9 混合加密。
+ *
+ * @param key 加密主公钥（64 字节 / SPKI PEM）或加密主私钥（32 字节 / PKCS#8 PEM）。
+ * @param id 接收方标识。
+ * @param message 明文（hex / Uint8Array；空消息传 `new Uint8Array(0)`）。
+ * @param opts `iv` 可选，默认随机 12 字节。
+ * @returns sealed hex（版本化，与 SM2 hybrid 同一布局）。
+ */
+export function hybridEncrypt(key, id, message, opts = {}) {
+    const k = keyArg(key, 64, 'key');
+    const idB = toBytes(id, 'id');
+    const msg = toMessageBytes(message, 'message');
+    const iv = resolveIv(opts.iv);
+    // DEK 固定为 SM4-128 的 16 字节；封装方不需要 KGC 的加密主私钥。
+    const kem = k.kind === 'public'
+        ? kemEncapsulateWithMasterPublic(k.bytes, idB, DEM_KEY_LEN)
+        : kemEncrypt(k.bytes, idB, DEM_KEY_LEN);
+    const enc = hexToBytes(kem.encapsulation, 'encapsulation');
+    const { ct, tag } = encryptGCM(kem.key, iv, msg, enc);
+    return bytesToHex(encodeSealed({
+        version: SEALED_VERSION,
+        klen: DEM_KEY_LEN,
+        encapsulation: enc,
+        iv,
+        tag: hexToBytes(tag, 'tag'),
+        ct: ct.length === 0 ? new Uint8Array(0) : hexToBytes(ct, 'ct'),
+    }));
+}
+export function hybridDecrypt(ke, id, sealed, opts = {}) {
+    try {
+        const parts = decodeSealed(sealed);
+        if (parts.klen !== DEM_KEY_LEN) {
+            throw new InvalidCiphertextError(`sm9.hybridDecrypt: sealed.klen=${parts.klen}，当前版本只支持 ${DEM_KEY_LEN}`);
+        }
+        if (parts.encapsulation.length !== 65) {
+            throw new InvalidCiphertextError(`sm9.hybridDecrypt: encapsulation 必须是 65 字节，实际 ${parts.encapsulation.length}`);
+        }
+        // KEM 只算 K；错误 id 不会在这里报错，由下面的 GCM tag 兜底。
+        const key = kemDecrypt(ke, id, parts.encapsulation, parts.klen);
+        return decryptGCM(key, parts.iv, parts.ct, parts.tag, { aad: parts.encapsulation });
+    }
+    catch (err) {
+        if (opts.safeMode && err instanceof CiphertextError)
+            return null;
+        throw err;
+    }
+}

package/dist/sm9/index.d.ts

@@ -9,6 +9,8 @@
  * - `verify(ks, id, msg, sig)`：SM9 验签，通过返回 true
  * - `encrypt(ke, id, msg, r?)`：SM9 加密，输出 C1||C3||C2 hex（C1=65B, C3=32B, C2=|msg|）
  * - `decrypt(ke, id, ct)`：SM9 解密，输出明文 hex；C3 HMAC 校验失败抛错
+ * - `kemEncrypt` / `kemDecrypt`：KEM（GM/T 0044.4，见 `./kem.ts`）
+ * - `hybridEncrypt` / `hybridDecrypt`：KEM + SM4-GCM 混合加密（见 `./hybrid.ts`）
  *
  * 输入/输出 hex 全部不带 0x 前缀。
  * r 不传时由宿主 CSPRNG 提供（Node: crypto.randomBytes / 浏览器: crypto.getRandomValues）。
@@ -22,8 +24,8 @@
  *
  * spec/plan 对应：plan Task 10；spec §6 API、§12.1 Q2（同步优先）、Q3（PKCS#8 + SM9 OID）。
  */
-/** 预热 WASM 模块。 */
-export declare function ensureLoaded(): Promise<void>;
+import { ensureLoaded } from './core.js';
+export { ensureLoaded };
 /** SM9 主密钥用途。 */
 export type Sm9KeyPurpose = 'sign' | 'enc';
 /** `generateKeyPair` 选项。 */
@@ -125,30 +127,7 @@ export declare function decrypt(ke: string | Uint8Array, id: string | Uint8Array
     safeMode: true;
 }): string | null;
 export declare function decrypt(ke: string | Uint8Array, id: string | Uint8Array, ct: string | Uint8Array, opts?: Sm9DecryptOptions): string;
-/** KEM 封装结果。 */
-export interface KemResult {
-    /** 会话密钥 K（hex，长度为 `2*klen`）。 */
-    key: string;
-    /** 封装点 C1（65 字节未压缩 G1 点 hex：`04 || x || y`）。 */
-    encapsulation: string;
-}
-/**
- * SM9 密钥封装（GM/T 0044.4）：用接收方 id 与其加密主公钥 [ke]P1 封装一个会话密钥。
- *
- * @param ke   32 字节加密主私钥 hex（用于派生主公钥 [ke]P1）
- * @param id   接收方标识
- * @param klen 会话密钥字节长度（默认 32）
- * @param r    32 字节随机数 hex（可选；不传则由宿主 CSPRNG 提供）
- * @returns    `{ key, encapsulation }`
- */
-export declare function kemEncrypt(ke: string | Uint8Array, id: string | Uint8Array, klen?: number, r?: string | Uint8Array): KemResult;
-/**
- * SM9 密钥解封装：用本端加密主私钥 ke 与 id 从封装点 C1 恢复会话密钥。
- *
- * @param encapsulation 65 字节封装点 C1 hex
- * @returns 会话密钥 hex
- */
-export declare function kemDecrypt(ke: string | Uint8Array, id: string | Uint8Array, encapsulation: string | Uint8Array, klen?: number): string;
+export { type KemResult, kemDecrypt, kemEncrypt } from './kem.js';
 /** 密钥交换端点配置。 */
 export interface Sm9ExchangeOptions {
     /** 会话密钥字节长度（默认 32）。 */
@@ -193,3 +172,4 @@ export declare function createExchangeInitiator(ke: string | Uint8Array, selfId:
  * @param peerId 对端（A）标识 ID_A
  */
 export declare function createExchangeResponder(ke: string | Uint8Array, selfId: string | Uint8Array, peerId: string | Uint8Array, options?: Sm9ExchangeOptions): Promise<Sm9KeyExchangeResponder>;
+export * from './hybrid.js';

package/dist/sm9/index.js

@@ -9,6 +9,8 @@
  * - `verify(ks, id, msg, sig)`：SM9 验签，通过返回 true
  * - `encrypt(ke, id, msg, r?)`：SM9 加密，输出 C1||C3||C2 hex（C1=65B, C3=32B, C2=|msg|）
  * - `decrypt(ke, id, ct)`：SM9 解密，输出明文 hex；C3 HMAC 校验失败抛错
+ * - `kemEncrypt` / `kemDecrypt`：KEM（GM/T 0044.4，见 `./kem.ts`）
+ * - `hybridEncrypt` / `hybridDecrypt`：KEM + SM4-GCM 混合加密（见 `./hybrid.ts`）
  *
  * 输入/输出 hex 全部不带 0x 前缀。
  * r 不传时由宿主 CSPRNG 提供（Node: crypto.randomBytes / 浏览器: crypto.getRandomValues）。
@@ -22,152 +24,12 @@
  *
  * spec/plan 对应：plan Task 10；spec §6 API、§12.1 Q2（同步优先）、Q3（PKCS#8 + SM9 OID）。
  */
-import { encodeSm9PrivateKeyPem, encodeSm9PublicKeyPem, parseSm9PrivateKeyPem, parseSm9PublicKeyPem, } from '../pem/sm9.js';
+import { encodeSm9PrivateKeyPem, encodeSm9PublicKeyPem } from '../pem/sm9.js';
 import { bytesToHex, hexToBytes } from '../runtime/convert.js';
-import { CiphertextError, DecryptionError, InvalidCiphertextError, InvalidKeyError, } from '../runtime/errors.js';
-import { loadWasm } from '../runtime/loadWasm.js';
-import { randomScalarBelow } from '../runtime/random.js';
-/** SM9 曲线阶 n。 */
-const N = BigInt('0xb640000002a3a6f1d603ab4ff58ec74449f2934b18ea8beee56ee19cd69ecf25');
-/** 预热 WASM 模块。 */
-export async function ensureLoaded() {
-    if (globalThis.__sm9Wasm)
-        return;
-    const mod = await loadWasm('sm9');
-    globalThis.__sm9Wasm = {
-        exports: mod.exports,
-        memory: mod.memory,
-    };
-}
-function getModule() {
-    const m = globalThis.__sm9Wasm;
-    if (!m)
-        throw new Error('sm9: 未初始化，请先 `await ensureLoaded()`。');
-    return m;
-}
-// ---------------- 工具 ----------------
-/** 任意输入 → Uint8Array。
- *  - Uint8Array: 拷一份
- *  - string 且看起来是 hex（偶数长度 + 全部 0-9a-fA-F）：按 hex 解
- *  - 其他 string：按 UTF-8 编码（用于 id、msg 等人类可读输入）
- * 失败抛 TypeError。 */
-/**
- * 通用输入归一化：Uint8Array 拷贝、hex 解码、其它按 UTF-8。
- *
- * **刻意不做 PEM 嗅探** —— PEM 只可能出现在密钥参数上，由 `masterPrivateBytes`
- * 显式处理；这样 id / msg 里出现 `-----BEGIN` 也不会被误吞。
- */
-function toBytes(input, label) {
-    if (input instanceof Uint8Array)
-        return new Uint8Array(input);
-    if (typeof input !== 'string')
-        throw new TypeError(`sm9: ${label} 必须是字符串或 Uint8Array`);
-    if (input.startsWith('0x') || /^[0-9a-fA-F]+$/.test(input)) {
-        const s = input.startsWith('0x') ? input.slice(2) : input;
-        if (s.length % 2 !== 0)
-            throw new TypeError(`sm9: ${label} hex 长度必须为偶数`);
-        return hexToBytes(s, label);
-    }
-    return new TextEncoder().encode(input);
-}
-/**
- * 主私钥参数归一化：接受 32 字节（hex / Uint8Array）或 PKCS#8 私钥 PEM
- * （spec §12.1 Q3，算法 OID `1.2.156.10197.1.100`）。
- */
-function masterPrivateBytes(input, label) {
-    let bytes;
-    if (typeof input === 'string' && input.includes('-----BEGIN')) {
-        const parsed = parseSm9PrivateKeyPem(input);
-        if (parsed.length !== 32) {
-            throw new InvalidKeyError(`sm9: ${label} 作为 PEM 主私钥应为 32 字节，实际 ${parsed.length}`);
-        }
-        bytes = parsed;
-    }
-    else {
-        const b = toBytes(input, label);
-        if (b.length !== 32) {
-            throw new InvalidKeyError(`sm9: ${label} 必须是 32 字节主私钥，实际 ${b.length}`);
-        }
-        bytes = b;
-    }
-    // 标量范围：SM9（GM/T 0044）要求 1 ≤ k ≤ n−1。
-    // 越界值不会崩，但 wasm 侧的 addModN → modAdd 只做一次条件减、要求输入已
-    // 约化（h1 + k < 2n），k ≥ n 时 k + h1 可能 ≥ 2n 而静默产出错值，故在此显式拒绝。
-    const k = BigInt(`0x${bytesToHex(bytes)}`);
-    if (k < 1n || k >= N) {
-        throw new InvalidKeyError(`sm9: ${label} 必须在 [1, n−1] 范围内（SM9 主私钥标量）`);
-    }
-    return bytes;
-}
-/** 主公钥参数归一化：64（加密 G1）或 128（签名 G2）字节点，或 SPKI 主公钥 PEM。 */
-function masterPublicBytes(input, label) {
-    if (typeof input === 'string' && input.includes('-----BEGIN')) {
-        const pub = parseSm9PublicKeyPem(input);
-        if (pub.length !== 64 && pub.length !== 128) {
-            throw new InvalidKeyError(`sm9: ${label} 作为 PEM 主公钥必须是 64 或 128 字节，实际 ${pub.length}`);
-        }
-        return pub;
-    }
-    const b = toBytes(input, label);
-    if (b.length !== 64 && b.length !== 128) {
-        throw new InvalidKeyError(`sm9: ${label} 必须是 64（加密）或 128（签名）字节主公钥，实际 ${b.length}`);
-    }
-    return b;
-}
-/**
- * 解析 `verify` / `encrypt` 的密钥参数：主私钥（32 字节 / PKCS#8 私钥 PEM）
- * 或主公钥（`publicLen` 字节点 / SPKI 公钥 PEM）。
- *
- * 两者的长度区间不重叠（主私钥恒为 32 字节），因此按长度即可判别。
- */
-function keyArg(input, publicLen, label) {
-    if (typeof input === 'string' && input.includes('-----BEGIN')) {
-        if (input.includes('BEGIN PUBLIC KEY')) {
-            const pub = parseSm9PublicKeyPem(input);
-            if (pub.length !== publicLen) {
-                throw new InvalidKeyError(`sm9: ${label} 作为 PEM 主公钥应为 ${publicLen} 字节，实际 ${pub.length}`);
-            }
-            return { kind: 'public', bytes: pub };
-        }
-        return { kind: 'secret', bytes: masterPrivateBytes(input, label) };
-    }
-    const b = toBytes(input, label);
-    if (b.length === 32)
-        return { kind: 'secret', bytes: b };
-    if (b.length === publicLen)
-        return { kind: 'public', bytes: b };
-    throw new InvalidKeyError(`sm9: ${label} 必须是 32 字节主私钥或 ${publicLen} 字节主公钥，实际 ${b.length}`);
-}
-/**
- * 校验字节长度。默认按**密钥支**（`InvalidKeyError`）抛错 —— SM9 各入口的参数绝大多数
- * 是主私钥 / 标量；密文、签名、协议消息的调用点显式传 `'cipher'`。
- */
-function requireLen(b, n, label, kind = 'key') {
-    if (b.length === n)
-        return;
-    const msg = `sm9: ${label} 必须是 ${n} 字节，实际 ${b.length}`;
-    if (kind === 'cipher')
-        throw new InvalidCiphertextError(msg);
-    throw new InvalidKeyError(msg);
-}
-function mem() {
-    return new Uint8Array(getModule().memory.buffer);
-}
-function _allocBytes(n) {
-    return getModule().exports.alloc(n);
-}
-function putHex(hex, ptr) {
-    mem().set(hexToBytes(hex), ptr);
-}
-function putBytes(b, ptr) {
-    mem().set(b, ptr);
-}
-function readHex(ptr, len) {
-    return bytesToHex(mem().subarray(ptr, ptr + len));
-}
-function randomRHex() {
-    return randomScalarBelow(N).toString(16).padStart(64, '0');
-}
+import { CiphertextError, DecryptionError, InvalidCiphertextError } from '../runtime/errors.js';
+import { ensureLoaded, getModule, mem } from './core.js';
+import { keyArg, masterPrivateBytes, masterPublicBytes, putBytes, putHex, randomRHex, readHex, requireLen, toBytes, } from './input.js';
+export { ensureLoaded };
 /**
  * 生成 SM9 主密钥对与对应用户私钥（spec §6、§12.1 Q3）。
  *
@@ -443,73 +305,8 @@ function decryptUnsafe(ke, id, ct) {
         exports.freeAll();
     }
 }
-/**
- * SM9 密钥封装（GM/T 0044.4）：用接收方 id 与其加密主公钥 [ke]P1 封装一个会话密钥。
- *
- * @param ke   32 字节加密主私钥 hex（用于派生主公钥 [ke]P1）
- * @param id   接收方标识
- * @param klen 会话密钥字节长度（默认 32）
- * @param r    32 字节随机数 hex（可选；不传则由宿主 CSPRNG 提供）
- * @returns    `{ key, encapsulation }`
- */
-export function kemEncrypt(ke, id, klen = 32, r) {
-    const keB = masterPrivateBytes(ke, 'ke');
-    const idB = toBytes(id, 'id');
-    const rB = r !== undefined ? toBytes(r, 'r') : toBytes(randomRHex(), 'r');
-    requireLen(rB, 32, 'r');
-    if (!Number.isInteger(klen) || klen <= 0)
-        throw new RangeError('sm9: klen 必须为正整数');
-    const { exports } = getModule();
-    const keP = exports.alloc(32);
-    const idP = exports.alloc(idB.length);
-    const rP = exports.alloc(32);
-    const c1P = exports.alloc(65);
-    const kP = exports.alloc(klen);
-    try {
-        putBytes(keB, keP);
-        putBytes(idB, idP);
-        putBytes(rB, rP);
-        const rc = exports.sm9KemEncryptOut(keP, idP, idB.length, rP, klen, c1P, kP);
-        if (rc !== 1)
-            throw new Error('sm9: kemEncrypt 失败（K 全 0，需换随机数重试）');
-        return { key: readHex(kP, klen), encapsulation: readHex(c1P, 65) };
-    }
-    finally {
-        exports.freeAll();
-    }
-}
-/**
- * SM9 密钥解封装：用本端加密主私钥 ke 与 id 从封装点 C1 恢复会话密钥。
- *
- * @param encapsulation 65 字节封装点 C1 hex
- * @returns 会话密钥 hex
- */
-export function kemDecrypt(ke, id, encapsulation, klen = 32) {
-    const keB = masterPrivateBytes(ke, 'ke');
-    const idB = toBytes(id, 'id');
-    const c1B = toBytes(encapsulation, 'encapsulation');
-    if (c1B.length !== 65)
-        throw new RangeError(`sm9: encapsulation 必须是 65 字节，实际 ${c1B.length}`);
-    if (!Number.isInteger(klen) || klen <= 0)
-        throw new RangeError('sm9: klen 必须为正整数');
-    const { exports } = getModule();
-    const keP = exports.alloc(32);
-    const idP = exports.alloc(idB.length);
-    const c1P = exports.alloc(65);
-    const kP = exports.alloc(klen);
-    try {
-        putBytes(keB, keP);
-        putBytes(idB, idP);
-        putBytes(c1B, c1P);
-        const rc = exports.sm9KemDecryptOut(keP, idP, idB.length, c1P, klen, kP);
-        if (rc !== 1)
-            throw new DecryptionError('sm9: kemDecrypt 失败（封装非法 / K 全 0）');
-        return readHex(kP, klen);
-    }
-    finally {
-        exports.freeAll();
-    }
-}
+// KEM 实现拆到 ./kem.ts，供 hybrid.ts 复用且避免循环依赖。
+export { kemDecrypt, kemEncrypt } from './kem.js';
 function ctEq(a, b) {
     if (a.length !== b.length)
         return false;
@@ -678,3 +475,5 @@ export async function createExchangeResponder(ke, selfId, peerId, options = {})
         },
     };
 }
+// SM9 混合加密（KEM + SM4-GCM）。
+export * from './hybrid.js';