sm-crypto-wasm 0.1.2 → 0.3.0

package/dist/sm2/index.d.ts

@@ -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 公钥）。
@@ -70,14 +72,54 @@ export interface Sm2DecryptOptions {
  * @returns PKCS#8 私钥 PEM 与 SPKI 公钥 PEM。
  */
 export declare function generateKeyPair(): Promise<Sm2KeyPair>;
+/**
+ * 池中的一个预计算签名点。
+ *
+ * `point`（`k·G` 的坐标）是公开信息；**`k` 被封在模块内部**，外部读不到，被
+ * `sign()` 取走后立刻从索引中摘除并抹掉字节 —— 所以"复用同一个 `k`"在 API 层面
+ * 就不可能发生，调用方不需要（也无法）自己去保证这一点。
+ */
+export declare class SignaturePoint {
+    /** `k·G` 的仿射坐标 `x ‖ y`（64 字节 hex）。公开信息，可用于审计。 */
+    readonly point: string;
+    /** 只允许本模块的 `createSignaturePointPool` 构造。 */
+    private constructor();
+    /** @internal 仅供 `createSignaturePointPool` 使用。 */
+    static _create(nonce: Uint8Array, point: string): SignaturePoint;
+}
+/** `sign` 的选项。 */
+export interface SignOptions {
+    /**
+     * 预计算的签名点池（见 `createSignaturePointPool`）。
+     *
+     * 命中时省掉本次签名的固定基点标量乘（实测占单次签名的 56%）；池被取空后
+     * 自动回退到现算。**该数组会被原地消费**（每签一次 `pop()` 一个点），
+     * 调用方无需自己维护游标。
+     */
+    pointPool?: SignaturePoint[];
+}
+/**
+ * 预计算 `n` 个签名点，供 `sign()` 的 `pointPool` 选项消费。
+ *
+ * 每个点 = 一次 `k·G`（本机约 130 µs）。批量签名时把这些固定基点标量乘提前
+ * 摊销，签名的关键路径只剩 `e = SM3(Z ‖ M)` 与两条模运算 —— 实测快 5.9×。
+ *
+ * `k` 取自宿主 CSPRNG，并由本模块独占保管：调用方拿不到它，也就无从误用成复用。
+ * 唯一的约定是"同一个点只喂一次"，而真喂两次会直接抛错。
+ *
+ * @param n 生成个数。
+ * @returns `n` 个签名点。
+ */
+export declare function createSignaturePointPool(n: number): Promise<SignaturePoint[]>;
 /**
  * SM2 签名（默认 SM3withSM2、默认用户标识）。
  *
  * @param privateKey 32 字节私钥。
  * @param message 待签名消息。
+ * @param opts `pointPool`：预计算的签名点池（见 `createSignaturePointPool`）。
  * @returns 64 字节签名（r || s）的 hex。
  */
-export declare function sign(privateKey: string | Uint8Array, message: string | Uint8Array): string;
+export declare function sign(privateKey: string | Uint8Array, message: string | Uint8Array, opts?: SignOptions): string;
 /**
  * SM2 验签。
  *
@@ -109,3 +151,5 @@ export declare function decrypt(privateKey: string | Uint8Array, ciphertext: str
 }): string | null;
 export declare function decrypt(privateKey: string | Uint8Array, ciphertext: string | Uint8Array, opts?: Sm2DecryptOptions): string;
 export * from './exchange.js';
+export * from './hybrid.js';
+export * from './kem.js';

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 公钥）。
@@ -215,34 +217,122 @@ function randomK() {
     }
     return out;
 }
+/**
+ * 池中的一个预计算签名点。
+ *
+ * `point`（`k·G` 的坐标）是公开信息；**`k` 被封在模块内部**，外部读不到，被
+ * `sign()` 取走后立刻从索引中摘除并抹掉字节 —— 所以"复用同一个 `k`"在 API 层面
+ * 就不可能发生，调用方不需要（也无法）自己去保证这一点。
+ */
+export class SignaturePoint {
+    /** `k·G` 的仿射坐标 `x ‖ y`（64 字节 hex）。公开信息，可用于审计。 */
+    point;
+    /** 只允许本模块的 `createSignaturePointPool` 构造。 */
+    constructor(point) {
+        this.point = point;
+    }
+    /** @internal 仅供 `createSignaturePointPool` 使用。 */
+    static _create(nonce, point) {
+        const p = new SignaturePoint(point);
+        POINT_NONCE.set(p, nonce);
+        return p;
+    }
+}
+/**
+ * 点位 → 一次性 `k`。取走即 `delete`：同一个点位对象无论被谁持有引用，都只能
+ * 取到一次 `k`。用 `WeakMap` 而非对象属性，是为了连"枚举键名"都做不到。
+ */
+const POINT_NONCE = new WeakMap();
+/**
+ * 取走签名点的一次性 `k`。
+ *
+ * 索引里没有（已被取过，或不是本库产出的伪造对象）就抛错 —— 于是"同一个点签两次"
+ * 会当场失败，而不是悄悄复用 `k` 把私钥送出去。
+ */
+function takeNonce(p) {
+    const nonce = POINT_NONCE.get(p);
+    if (nonce === undefined) {
+        throw new Error('sm2: 该签名点不可用（已被使用过，或不是 createSignaturePointPool 产出的）；签名点是一次性的。');
+    }
+    POINT_NONCE.delete(p);
+    return nonce;
+}
+/**
+ * 预计算 `n` 个签名点，供 `sign()` 的 `pointPool` 选项消费。
+ *
+ * 每个点 = 一次 `k·G`（本机约 130 µs）。批量签名时把这些固定基点标量乘提前
+ * 摊销，签名的关键路径只剩 `e = SM3(Z ‖ M)` 与两条模运算 —— 实测快 5.9×。
+ *
+ * `k` 取自宿主 CSPRNG，并由本模块独占保管：调用方拿不到它，也就无从误用成复用。
+ * 唯一的约定是"同一个点只喂一次"，而真喂两次会直接抛错。
+ *
+ * @param n 生成个数。
+ * @returns `n` 个签名点。
+ */
+export async function createSignaturePointPool(n) {
+    if (!Number.isInteger(n) || n < 0) {
+        throw new RangeError(`sm2: 签名点池大小必须是非负整数，收到 ${String(n)}`);
+    }
+    await ensureLoaded();
+    const { exports, memory } = getModule();
+    const pool = [];
+    for (let i = 0; i < n; i++) {
+        const nonce = randomK();
+        const kPtr = exports.alloc(32);
+        const ptPtr = exports.alloc(64);
+        try {
+            new Uint8Array(memory.buffer, kPtr, 32).set(nonce);
+            exports.scalarMulGOut(kPtr, ptPtr);
+            pool.push(SignaturePoint._create(nonce, fromBytes(new Uint8Array(memory.buffer, ptPtr, 64).slice(), 'hex')));
+        }
+        finally {
+            exports.freeAll();
+        }
+    }
+    return pool;
+}
 /**
  * SM2 签名（默认 SM3withSM2、默认用户标识）。
  *
  * @param privateKey 32 字节私钥。
  * @param message 待签名消息。
+ * @param opts `pointPool`：预计算的签名点池（见 `createSignaturePointPool`）。
  * @returns 64 字节签名（r || s）的 hex。
  */
-export function sign(privateKey, message) {
+export function sign(privateKey, message, opts = {}) {
     const d = toPrivateKeyBytes(privateKey);
     const m = toBytes(message, 'message');
     const pub = derivePublicKeyBytes(d);
-    const { exports } = getModule();
+    const { exports, memory } = getModule();
     const dp = exports.alloc(32);
     const pxp = exports.alloc(32);
     const pyp = exports.alloc(32);
     const mp = exports.alloc(m.length);
     const kp = exports.alloc(32);
+    const xp = exports.alloc(32);
     const op = exports.alloc(64);
+    const pool = opts.pointPool;
     try {
         putBytes(d, dp);
         putBytes(pub.subarray(0, 32), pxp);
         putBytes(pub.subarray(32, 64), pyp);
         putBytes(m, mp);
-        // 最多重试几次 k（极小概率 r/s 为 0 或 r+k==n）。
+        // 最多重试几次 k（极小概率 r/s 为 0 或 r+k==n）。池命中时每轮换一个点。
         for (let attempt = 0; attempt < 16; attempt++) {
-            const k = randomK();
-            putBytes(k, kp);
-            const rc = exports.signOut(dp, pxp, pyp, mp, m.length, kp, op);
+            const pooled = pool?.pop();
+            let rc;
+            if (pooled !== undefined) {
+                // 一次性取走 k；此处之后该点不可再用（再喂会抛错）。
+                const nonce = takeNonce(pooled);
+                putBytes(nonce, kp);
+                nonce.fill(0); // JS 侧那份随即抹掉
+                new Uint8Array(memory.buffer, xp, 32).set(toBytes(pooled.point, 'point').subarray(0, 32));
+                rc = exports.signWithPointOut(dp, pxp, pyp, mp, m.length, kp, xp, op);
+            }
+            else {
+                putBytes(randomK(), kp);
+                rc = exports.signOut(dp, pxp, pyp, mp, m.length, kp, op);
+            }
             if (rc === 0) {
                 return fromBytes(readBytes(op, 64), 'hex');
             }
@@ -250,6 +340,8 @@ export function sign(privateKey, message) {
         throw new Error('sm2.sign: failed to produce a valid signature after retries');
     }
     finally {
+        // 抹掉 WASM 内存里那份 k（缓冲区在 freeAll 前仍可写）
+        new Uint8Array(memory.buffer, kp, 32).fill(0);
         exports.freeAll();
     }
 }
@@ -388,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/sm3/index.d.ts

@@ -7,6 +7,9 @@
  * 3. 拷入输入、调 `instance.exports.sm3(inputPtr, inputLen, outPtr)`。
  * 4. 从 outPtr 拷出 32 字节。
  *
+ * HMAC 的 ipad/opad 拼接与两次摘要调用都在 WASM 内完成（`exports.sm3Hmac`），
+ * 这一层只做参数归一化与缓冲区搬运。
+ *
  * spec/plan 对应：plan Task 7；spec §6 API、§9 安全姿态。
  */
 /**
@@ -22,7 +25,7 @@ export declare function ensureLoaded(): Promise<void>;
  */
 export declare function hash(input: string | Uint8Array): string;
 /**
- * HMAC-SM3（同步）。
+ * HMAC-SM3（同步，RFC 2104）。
  *
  * @param key 任意长度密钥。
  * @param msg 任意长度消息。

package/dist/sm3/index.js

@@ -7,6 +7,9 @@
  * 3. 拷入输入、调 `instance.exports.sm3(inputPtr, inputLen, outPtr)`。
  * 4. 从 outPtr 拷出 32 字节。
  *
+ * HMAC 的 ipad/opad 拼接与两次摘要调用都在 WASM 内完成（`exports.sm3Hmac`），
+ * 这一层只做参数归一化与缓冲区搬运。
+ *
  * spec/plan 对应：plan Task 7；spec §6 API、§9 安全姿态。
  */
 import { fromBytes, toBytes } from '../runtime/convert.js';
@@ -42,6 +45,10 @@ function digestInput(input, label) {
         return new Uint8Array(0);
     return toBytes(input, label);
 }
+/** `Uint8Array` 直接使用：紧接着就会 `set` 进 WASM 私有缓冲，再复制一份是纯浪费。 */
+function inputBytes(input, label) {
+    return input instanceof Uint8Array ? input : digestInput(input, label);
+}
 /**
  * SM3 摘要（同步）。
  *
@@ -49,7 +56,7 @@ function digestInput(input, label) {
  * @returns 32 字节摘要的 hex 字符串（64 字符）。
  */
 export function hash(input) {
-    const bytes = digestInput(input, 'msg');
+    const bytes = inputBytes(input, 'msg');
     const { exports, memory } = getModule();
     const inputLen = bytes.length;
     // 从 WASM 堆分配缓冲区；**不可**用固定地址，否则覆盖 AS runtime 数据。
@@ -66,30 +73,30 @@ export function hash(input) {
     }
 }
 /**
- * HMAC-SM3（同步）。
+ * HMAC-SM3（同步，RFC 2104）。
  *
  * @param key 任意长度密钥。
  * @param msg 任意长度消息。
  * @returns 32 字节摘要的 hex 字符串。
  */
 export function hmac(key, msg) {
-    const k = digestInput(key, 'key');
-    const m = digestInput(msg, 'msg');
-    const blockKey = k.length > 64 ? toBytes(hash(k), 'key64') : k;
-    const padded = new Uint8Array(64);
-    padded.set(blockKey);
-    const innerKey = new Uint8Array(64);
-    for (let i = 0; i < 64; i++)
-        innerKey[i] = (padded[i] ?? 0) ^ 0x36;
-    const outerKey = new Uint8Array(64);
-    for (let i = 0; i < 64; i++)
-        outerKey[i] = (padded[i] ?? 0) ^ 0x5c;
-    const innerMsg = new Uint8Array(64 + m.length);
-    innerMsg.set(innerKey, 0);
-    innerMsg.set(m, 64);
-    const inner = toBytes(hash(innerMsg), 'inner');
-    const outerMsg = new Uint8Array(64 + 32);
-    outerMsg.set(outerKey, 0);
-    outerMsg.set(inner, 64);
-    return hash(outerMsg);
+    const k = inputBytes(key, 'key');
+    const m = inputBytes(msg, 'msg');
+    const { exports, memory } = getModule();
+    // 空 key / 空 msg 也要占 1 字节：`alloc(0)` 返回的地址不保证可写。
+    const keyPtr = exports.alloc(k.length === 0 ? 1 : k.length);
+    const msgPtr = exports.alloc(m.length === 0 ? 1 : m.length);
+    const outPtr = exports.alloc(32);
+    try {
+        if (k.length > 0)
+            new Uint8Array(memory.buffer, keyPtr, k.length).set(k);
+        if (m.length > 0)
+            new Uint8Array(memory.buffer, msgPtr, m.length).set(m);
+        exports.sm3Hmac(keyPtr, k.length, msgPtr, m.length, outPtr);
+        const out = new Uint8Array(memory.buffer, outPtr, 32).slice();
+        return fromBytes(out, 'hex');
+    }
+    finally {
+        exports.freeAll();
+    }
 }

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;