sm-crypto-wasm 0.2.1 → 0.3.0

package/dist/sm9/input.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SM9 输入归一化与密钥参数校验。
+ *
+ * 从 `index.ts` 拆出，供 `kem.ts` / `hybrid.ts` 复用，避免循环依赖。
+ */
+/**
+ * 通用输入归一化：Uint8Array 拷贝、hex 解码、其它按 UTF-8。
+ *
+ * **刻意不做 PEM 嗅探** —— PEM 只可能出现在密钥参数上，由 `masterPrivateBytes`
+ * 显式处理；这样 id / msg 里出现 `-----BEGIN` 也不会被误吞。
+ */
+export declare function toBytes(input: string | Uint8Array, label: string): Uint8Array;
+/**
+ * 主私钥参数归一化：接受 32 字节（hex / Uint8Array）或 PKCS#8 私钥 PEM
+ * （spec §12.1 Q3，算法 OID `1.2.156.10197.1.100`）。
+ */
+export declare function masterPrivateBytes(input: string | Uint8Array, label: string): Uint8Array;
+/** 主公钥参数归一化：64（加密 G1）或 128（签名 G2）字节点，或 SPKI 主公钥 PEM。 */
+export declare function masterPublicBytes(input: string | Uint8Array, label: string): Uint8Array;
+/** `verify` / `encrypt` 第一参数的解析结果。 */
+export type KeyArg = {
+    kind: 'secret';
+    bytes: Uint8Array;
+} | {
+    kind: 'public';
+    bytes: Uint8Array;
+};
+/**
+ * 解析 `verify` / `encrypt` 的密钥参数：主私钥（32 字节 / PKCS#8 私钥 PEM）
+ * 或主公钥（`publicLen` 字节点 / SPKI 公钥 PEM）。
+ *
+ * 两者的长度区间不重叠（主私钥恒为 32 字节），因此按长度即可判别。
+ */
+export declare function keyArg(input: string | Uint8Array, publicLen: 64 | 128, label: string): KeyArg;
+/**
+ * 校验字节长度。默认按**密钥支**（`InvalidKeyError`）抛错 —— SM9 各入口的参数绝大多数
+ * 是主私钥 / 标量；密文、签名、协议消息的调用点显式传 `'cipher'`。
+ */
+export declare function requireLen(b: Uint8Array, n: number, label: string, kind?: 'key' | 'cipher'): void;
+export declare function putHex(hex: string, ptr: number): void;
+export declare function putBytes(b: Uint8Array, ptr: number): void;
+export declare function readHex(ptr: number, len: number): string;
+export declare function randomRHex(): string;

package/dist/sm9/input.js

@@ -0,0 +1,121 @@
+/**
+ * SM9 输入归一化与密钥参数校验。
+ *
+ * 从 `index.ts` 拆出，供 `kem.ts` / `hybrid.ts` 复用，避免循环依赖。
+ */
+import { parseSm9PrivateKeyPem, parseSm9PublicKeyPem } from '../pem/sm9.js';
+import { bytesToHex, hexToBytes } from '../runtime/convert.js';
+import { InvalidCiphertextError, InvalidKeyError } from '../runtime/errors.js';
+import { randomScalarBelow } from '../runtime/random.js';
+import { mem, N } from './core.js';
+/**
+ * 通用输入归一化：Uint8Array 拷贝、hex 解码、其它按 UTF-8。
+ *
+ * **刻意不做 PEM 嗅探** —— PEM 只可能出现在密钥参数上，由 `masterPrivateBytes`
+ * 显式处理；这样 id / msg 里出现 `-----BEGIN` 也不会被误吞。
+ */
+export 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`）。
+ */
+export 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。 */
+export 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 字节），因此按长度即可判别。
+ */
+export 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'`。
+ */
+export 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);
+}
+export function putHex(hex, ptr) {
+    mem().set(hexToBytes(hex), ptr);
+}
+export function putBytes(b, ptr) {
+    mem().set(b, ptr);
+}
+export function readHex(ptr, len) {
+    return bytesToHex(mem().subarray(ptr, ptr + len));
+}
+export function randomRHex() {
+    return randomScalarBelow(N).toString(16).padStart(64, '0');
+}

package/dist/sm9/kem.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SM9 密钥封装（KEM，GM/T 0044.4）。
+ *
+ * 两种封装入口：
+ * - `kemEncrypt(ke, id, klen, r?)`：用加密主私钥派生 Ppub-e（既有已发布接口）。
+ * - `kemEncapsulateWithMasterPublic(pub, id, klen, r?)`：直接用加密主公钥
+ *   `[ke]P1`（发送方的典型形态；供 `hybrid.ts` 使用，不改变既有 `kemEncrypt`）。
+ *
+ * 解封装只有 `kemDecrypt(ke, id, encapsulation, klen)`：必须持有加密主私钥。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 4。
+ */
+/** 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;
+/**
+ * 用加密主公钥封装的内部入口（`hybridEncrypt` 使用）。
+ *
+ * 与 `kemEncrypt` 的区别只在密钥参数：这里不需要 KGC 的加密主私钥。
+ *
+ * @param masterPublicKey 64 字节加密主公钥 `[ke]P1`（点字节 / SPKI 主公钥 PEM）。
+ * @param id 接收方标识。
+ * @param klen 会话密钥字节长度（默认 32）。
+ * @param r 32 字节随机数 hex（可选）。
+ */
+export declare function kemEncapsulateWithMasterPublic(masterPublicKey: 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;

package/dist/sm9/kem.js

@@ -0,0 +1,123 @@
+/**
+ * SM9 密钥封装（KEM，GM/T 0044.4）。
+ *
+ * 两种封装入口：
+ * - `kemEncrypt(ke, id, klen, r?)`：用加密主私钥派生 Ppub-e（既有已发布接口）。
+ * - `kemEncapsulateWithMasterPublic(pub, id, klen, r?)`：直接用加密主公钥
+ *   `[ke]P1`（发送方的典型形态；供 `hybrid.ts` 使用，不改变既有 `kemEncrypt`）。
+ *
+ * 解封装只有 `kemDecrypt(ke, id, encapsulation, klen)`：必须持有加密主私钥。
+ *
+ * spec/plan 对应：`docs/superpowers/plans/2026-10-16-sm2-sm9-hybrid-encryption.md`
+ * Task 4。
+ */
+import { DecryptionError, InvalidKeyError } from '../runtime/errors.js';
+import { getModule } from './core.js';
+import { masterPrivateBytes, masterPublicBytes, putBytes, randomRHex, readHex, requireLen, toBytes, } from './input.js';
+function requireKlen(klen) {
+    if (!Number.isInteger(klen) || klen <= 0)
+        throw new RangeError('sm9: klen 必须为正整数');
+}
+/**
+ * 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');
+    requireKlen(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();
+    }
+}
+/**
+ * 用加密主公钥封装的内部入口（`hybridEncrypt` 使用）。
+ *
+ * 与 `kemEncrypt` 的区别只在密钥参数：这里不需要 KGC 的加密主私钥。
+ *
+ * @param masterPublicKey 64 字节加密主公钥 `[ke]P1`（点字节 / SPKI 主公钥 PEM）。
+ * @param id 接收方标识。
+ * @param klen 会话密钥字节长度（默认 32）。
+ * @param r 32 字节随机数 hex（可选）。
+ */
+export function kemEncapsulateWithMasterPublic(masterPublicKey, id, klen = 32, r) {
+    const pub = masterPublicBytes(masterPublicKey, 'masterPublicKey');
+    if (pub.length !== 64) {
+        throw new InvalidKeyError(`sm9: masterPublicKey 必须是 64 字节加密主公钥，实际 ${pub.length}`);
+    }
+    const idB = toBytes(id, 'id');
+    const rB = r !== undefined ? toBytes(r, 'r') : toBytes(randomRHex(), 'r');
+    requireLen(rB, 32, 'r');
+    requireKlen(klen);
+    const { exports } = getModule();
+    const pubP = exports.alloc(64);
+    const idP = exports.alloc(idB.length);
+    const rP = exports.alloc(32);
+    const c1P = exports.alloc(65);
+    const kP = exports.alloc(klen);
+    try {
+        putBytes(pub, pubP);
+        putBytes(idB, idP);
+        putBytes(rB, rP);
+        const rc = exports.sm9KemEncryptPubOut(pubP, idP, idB.length, rP, klen, c1P, kP);
+        if (rc !== 1)
+            throw new Error('sm9: kemEncapsulate 失败（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}`);
+    requireKlen(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();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sm-crypto-wasm",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "国密 SM2/SM3/SM4/SM9/ZUC 的 WASM 实现，Node 18+ 与现代浏览器均可使用，按算法分包懒加载。",
   "description:en": "SM2/SM3/SM4/SM9/ZUC (China crypto) implemented in AssemblyScript -> WASM. Node 18+ & modern browsers, per-algorithm lazy loading.",
   "license": "Apache-2.0",