sm-crypto-wasm 0.1.0 → 0.1.2

package/dist/esbuild-plugin.d.ts

@@ -0,0 +1,70 @@
+/**
+ * esbuild 插件：把 `.wasm` 资源放到浏览器产物**运行时能解析到的位置**。
+ *
+ * ## 为什么需要它
+ *
+ * 浏览器版的加载器用 `fetch(new URL('../<algo>/<algo>.wasm', import.meta.url))` 取
+ * wasm（这个写法 Vite 与 Webpack 5 都会自动归档资源并重写 URL）。**esbuild 不会** ——
+ * 无论 `--outfile` 还是 `--outdir`，它都不搬 `new URL` 指向的文件（实测 0.28.2）。
+ * 结果：构建能过，运行时 `fetch` 404。
+ *
+ * 本插件在 build 结束后把 `dist/<algo>/<algo>.wasm` 复制到该相对位置：
+ * 运行时 URL 是相对**产物 JS 文件**的 `../<algo>/<algo>.wasm`，所以目标基目录是
+ * **产物 JS 所在目录的上级**（由 esbuild 的 `outdir` / `outfile` 推导）。
+ *
+ * ## 用法
+ *
+ * ```ts
+ * import { smCryptoWasm } from 'sm-crypto-wasm/esbuild-plugin';
+ *
+ * await esbuild.build({
+ *   entryPoints: ['src/main.ts'],
+ *   bundle: true,
+ *   platform: 'browser',
+ *   format: 'esm',
+ *   outdir: 'dist/assets',        // 产物 JS 落这里
+ *   plugins: [smCryptoWasm()],    // → wasm 复制到 dist/<algo>/<algo>.wasm
+ * });
+ * ```
+ *
+ * 建议把 `outdir` 指到子目录（如 `dist/assets`），这样 wasm 落在 `dist/<algo>/` 而不是
+ * 产物目录的上级。
+ *
+ * 只需用到部分算法时传 `algorithms` 少复制几个。
+ */
+/** 支持的算法名（与加载器白名单一致）。 */
+declare const WASM_ALGOS: readonly ['sm2', 'sm3', 'sm4', 'sm9', 'zuc'];
+export type WasmAlgo = (typeof WASM_ALGOS)[number];
+/** `smCryptoWasm()` 的选项。 */
+export interface SmCryptoWasmPluginOptions {
+    /** 只复制这些算法的 wasm（默认全部 5 个）。 */
+    algorithms?: readonly WasmAlgo[];
+    /** wasm 目标基目录。默认由 esbuild 的 `outdir` / `outfile` 推导（见模块注释）。 */
+    outDir?: string;
+    /** wasm 源目录。默认本包的 `dist/`（插件自身所在目录）。 */
+    sourceDir?: string;
+}
+/**
+ * esbuild 插件的**最小**结构。刻意不依赖 `esbuild` 的类型：这样本包不必把 esbuild
+ * 列为依赖，也不会因 esbuild 主版本升级而影响类型。
+ */
+export interface SmCryptoWasmPlugin {
+    name: string;
+    setup(build: {
+        initialOptions: {
+            outdir?: string;
+            outfile?: string;
+        };
+        onEnd: (cb: (result: {
+            errors: readonly unknown[];
+        }) => void | Promise<void>) => void;
+    }): void;
+}
+/**
+ * 创建 esbuild 插件：build 成功后复制 wasm 资源。
+ *
+ * @param options 见 {@link SmCryptoWasmPluginOptions}。
+ * @returns 可直接放进 `plugins` 数组的插件对象。
+ */
+export declare function smCryptoWasm(options?: SmCryptoWasmPluginOptions): SmCryptoWasmPlugin;
+export {};

package/dist/esbuild-plugin.js

@@ -0,0 +1,85 @@
+/**
+ * esbuild 插件：把 `.wasm` 资源放到浏览器产物**运行时能解析到的位置**。
+ *
+ * ## 为什么需要它
+ *
+ * 浏览器版的加载器用 `fetch(new URL('../<algo>/<algo>.wasm', import.meta.url))` 取
+ * wasm（这个写法 Vite 与 Webpack 5 都会自动归档资源并重写 URL）。**esbuild 不会** ——
+ * 无论 `--outfile` 还是 `--outdir`，它都不搬 `new URL` 指向的文件（实测 0.28.2）。
+ * 结果：构建能过，运行时 `fetch` 404。
+ *
+ * 本插件在 build 结束后把 `dist/<algo>/<algo>.wasm` 复制到该相对位置：
+ * 运行时 URL 是相对**产物 JS 文件**的 `../<algo>/<algo>.wasm`，所以目标基目录是
+ * **产物 JS 所在目录的上级**（由 esbuild 的 `outdir` / `outfile` 推导）。
+ *
+ * ## 用法
+ *
+ * ```ts
+ * import { smCryptoWasm } from 'sm-crypto-wasm/esbuild-plugin';
+ *
+ * await esbuild.build({
+ *   entryPoints: ['src/main.ts'],
+ *   bundle: true,
+ *   platform: 'browser',
+ *   format: 'esm',
+ *   outdir: 'dist/assets',        // 产物 JS 落这里
+ *   plugins: [smCryptoWasm()],    // → wasm 复制到 dist/<algo>/<algo>.wasm
+ * });
+ * ```
+ *
+ * 建议把 `outdir` 指到子目录（如 `dist/assets`），这样 wasm 落在 `dist/<algo>/` 而不是
+ * 产物目录的上级。
+ *
+ * 只需用到部分算法时传 `algorithms` 少复制几个。
+ */
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 支持的算法名（与加载器白名单一致）。 */
+const WASM_ALGOS = ['sm2', 'sm3', 'sm4', 'sm9', 'zuc'];
+/** 本包 `dist/` 的位置（编译后插件自身就在 `dist/` 下）。 */
+const THIS_DIST_DIR = dirname(fileURLToPath(import.meta.url));
+/**
+ * 推导 wasm 的目标基目录。
+ *
+ * 运行时相对**产物 JS 文件**解析 `../<algo>/<algo>.wasm`，所以目标是产物 JS 目录的上级。
+ * esbuild 通常把入口产物放在 `outdir` 根（单入口时 `outbase` 就是入口所在目录）。
+ */
+function resolveTargetBase(opts) {
+    if (opts.outdir)
+        return resolve(opts.outdir, '..');
+    if (opts.outfile)
+        return resolve(dirname(opts.outfile), '..');
+    return undefined;
+}
+/**
+ * 创建 esbuild 插件：build 成功后复制 wasm 资源。
+ *
+ * @param options 见 {@link SmCryptoWasmPluginOptions}。
+ * @returns 可直接放进 `plugins` 数组的插件对象。
+ */
+export function smCryptoWasm(options = {}) {
+    const algos = options.algorithms ?? WASM_ALGOS;
+    const sourceDir = options.sourceDir ?? THIS_DIST_DIR;
+    return {
+        name: 'sm-crypto-wasm-assets',
+        setup(build) {
+            build.onEnd((result) => {
+                // 构建失败时不产出资源，避免留下半套产物。
+                if (result.errors.length > 0)
+                    return;
+                const targetBase = options.outDir ?? resolveTargetBase(build.initialOptions);
+                if (targetBase === undefined)
+                    return; // `write: false` 等场景：没有落盘位置
+                for (const algo of algos) {
+                    const from = join(sourceDir, algo, `${algo}.wasm`);
+                    if (!existsSync(from))
+                        continue; // 只装了部分算法时静默跳过
+                    const to = join(targetBase, algo, `${algo}.wasm`);
+                    mkdirSync(dirname(to), { recursive: true });
+                    copyFileSync(from, to);
+                }
+            });
+        },
+    };
+}

package/dist/runtime/loadWasm.browser.d.ts

@@ -0,0 +1,39 @@
+/**
+ * WASM 加载器（**浏览器版**）。
+ *
+ * 打包时由 package.json 的 `browser` 字段替换 `loadWasm.js`。存在的唯一理由是：
+ * 浏览器的模块图里**不能出现 `node:*`** —— Webpack 5 / esbuild / Rspack 在解析期
+ * 就会因此构建失败（Vite 是少数会把 `node:*` 外部化成空 stub 的特例，不能依赖）。
+ * 本文件因此**零 `node:*` 引用**，共享逻辑在 `loadWasm.core.ts`。
+ *
+ * Node 环境下这个文件不会被用到（Node 用 `loadWasm.ts`）。
+ */
+import { type WasmAlgo, type WasmModule } from './loadWasm.core.js';
+export type { WasmAlgo, WasmModule } from './loadWasm.core.js';
+/**
+ * 异步加载并实例化 wasm。**这是业务代码的主入口**。
+ *
+ * 并发安全：同名的第二次调用复用第一次的 Promise，不会触发额外 instantiate。
+ * 调用前请确保已初始化（软件包文档里说明的 wasm 资源可被解析到）。
+ *
+ * @param name 算法名。
+ * @returns 解析后冻结的 WasmModule。
+ */
+export declare function loadWasm(name: WasmAlgo): Promise<WasmModule>;
+/**
+ * 同步加载：**浏览器端不可用**（`fetch` 本质上异步）。
+ *
+ * @param name 算法名。
+ * @throws 恒抛错，提示改用 `await loadWasm(name)`。
+ */
+export declare function loadWasmSync(name: WasmAlgo): WasmModule;
+/**
+ * 获取已缓存的 wasm 引用（若无则初始化）。等价于 `loadWasm`，提供语义化别名。
+ *
+ * @param name 算法名。
+ */
+export declare function getCachedWasm(name: WasmAlgo): Promise<WasmModule>;
+/**
+ * 清空缓存。仅供测试使用。
+ */
+export declare function _resetCacheForTests(): void;

package/dist/runtime/loadWasm.browser.js

@@ -0,0 +1,78 @@
+/**
+ * WASM 加载器（**浏览器版**）。
+ *
+ * 打包时由 package.json 的 `browser` 字段替换 `loadWasm.js`。存在的唯一理由是：
+ * 浏览器的模块图里**不能出现 `node:*`** —— Webpack 5 / esbuild / Rspack 在解析期
+ * 就会因此构建失败（Vite 是少数会把 `node:*` 外部化成空 stub 的特例，不能依赖）。
+ * 本文件因此**零 `node:*` 引用**，共享逻辑在 `loadWasm.core.ts`。
+ *
+ * Node 环境下这个文件不会被用到（Node 用 `loadWasm.ts`）。
+ */
+import { instantiateFromBuffer, isWasmAlgo, memoizeLoad, rejectBadName, resetCacheForTests, } from './loadWasm.core.js';
+/**
+ * 每个算法的 wasm URL。
+ *
+ * **显式列出**而不是用模板拼路径（`../${name}/${name}.wasm`）：打包器只能静态识别
+ * `new URL('./literal.wasm', import.meta.url)` 这种写法，才会把 wasm 归档进产物并
+ * 重写 URL；动态拼接出来的路径打包器既不会复制文件、也不会改写，运行时必然 404。
+ */
+const WASM_URLS = {
+    sm2: new URL('../sm2/sm2.wasm', import.meta.url),
+    sm3: new URL('../sm3/sm3.wasm', import.meta.url),
+    sm4: new URL('../sm4/sm4.wasm', import.meta.url),
+    sm9: new URL('../sm9/sm9.wasm', import.meta.url),
+    zuc: new URL('../zuc/zuc.wasm', import.meta.url),
+};
+/**
+ * 取 wasm 字节（浏览器路径：`fetch` 同级资源，URL 由打包器解析）。
+ *
+ * @param name 算法名。
+ * @returns wasm 二进制 ArrayBuffer（总是一次新的读取）。
+ */
+async function fetchWasm(name) {
+    const url = WASM_URLS[name];
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`loadWasm: failed to fetch ${url}: ${res.status} ${res.statusText}`);
+    }
+    return res.arrayBuffer();
+}
+/**
+ * 异步加载并实例化 wasm。**这是业务代码的主入口**。
+ *
+ * 并发安全：同名的第二次调用复用第一次的 Promise，不会触发额外 instantiate。
+ * 调用前请确保已初始化（软件包文档里说明的 wasm 资源可被解析到）。
+ *
+ * @param name 算法名。
+ * @returns 解析后冻结的 WasmModule。
+ */
+export function loadWasm(name) {
+    if (!isWasmAlgo(name))
+        rejectBadName(name);
+    return memoizeLoad(name, async (n) => instantiateFromBuffer(await fetchWasm(n)));
+}
+/**
+ * 同步加载：**浏览器端不可用**（`fetch` 本质上异步）。
+ *
+ * @param name 算法名。
+ * @throws 恒抛错，提示改用 `await loadWasm(name)`。
+ */
+export function loadWasmSync(name) {
+    if (!isWasmAlgo(name))
+        rejectBadName(name);
+    throw new Error('loadWasmSync: browser must await loadWasm() first');
+}
+/**
+ * 获取已缓存的 wasm 引用（若无则初始化）。等价于 `loadWasm`，提供语义化别名。
+ *
+ * @param name 算法名。
+ */
+export function getCachedWasm(name) {
+    return loadWasm(name);
+}
+/**
+ * 清空缓存。仅供测试使用。
+ */
+export function _resetCacheForTests() {
+    resetCacheForTests();
+}

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

@@ -0,0 +1,45 @@
+/**
+ * WASM 加载器共享核心（Node 版与浏览器版共用）。
+ *
+ * ## 为什么要拆 core
+ *
+ * `node:*` 内置模块**不能出现在浏览器构建的模块图里**：打包器（Webpack 5 /
+ * esbuild / Rspack）在**解析期**就会因 `node:fs` 之类的裸模块报错中止，而
+ * tree-shaking 帮不上忙 —— 解析先于摇树。所以：
+ *
+ * - Node 侧（读文件）实现放 `loadWasm.ts`；
+ * - 浏览器侧（fetch）实现放 `loadWasm.browser.ts`；
+ * - 由 package.json 的 `browser` 字段在打包时做文件替换；
+ * - **本文件两者共用，且零 `node:*` 引用**。
+ */
+/** 算法白名单：确保非法 `name` 在到达文件系统 / 网络前被拒绝。 */
+declare const WASM_ALGOS: readonly ['sm2', 'sm3', 'sm4', 'sm9', 'zuc'];
+export type WasmAlgo = (typeof WASM_ALGOS)[number];
+export declare function isWasmAlgo(name: unknown): name is WasmAlgo;
+export declare function rejectBadName(name: unknown): never;
+/** 加载完成后的 WASM 模块封装。`exports` 已类型化为 `WebAssembly.Exports`。 */
+export interface WasmModule {
+    readonly exports: WebAssembly.Exports;
+    readonly memory: WebAssembly.Memory;
+}
+/** ASC 默认产物会导入 `env` 模块（abort / trace / __assert_fail）。 */
+export declare const ASC_ENV: WebAssembly.Imports;
+/**
+ * 同步实例化 wasm。失败抛 WebAssembly 自身的 CompileError / LinkError。
+ *
+ * @param buf wasm 字节。
+ */
+export declare function instantiateFromBuffer(buf: ArrayBuffer): WasmModule;
+/**
+ * 按算法名记忆化加载：同名的第二次调用复用第一次的 Promise，并发安全
+ * （不会重复 instantiate）。
+ *
+ * @param name 算法名（调用方已校验）。
+ * @param loader 实际取字节 + 实例化的实现（Node / 浏览器各不相同）。
+ */
+export declare function memoizeLoad(name: WasmAlgo, loader: (name: WasmAlgo) => Promise<WasmModule>): Promise<WasmModule>;
+/**
+ * 清空缓存。仅供测试使用 —— 单元测试需要测并发安全场景时必须能重置状态。
+ */
+export declare function resetCacheForTests(): void;
+export {};

package/dist/runtime/loadWasm.core.js

@@ -0,0 +1,70 @@
+/**
+ * WASM 加载器共享核心（Node 版与浏览器版共用）。
+ *
+ * ## 为什么要拆 core
+ *
+ * `node:*` 内置模块**不能出现在浏览器构建的模块图里**：打包器（Webpack 5 /
+ * esbuild / Rspack）在**解析期**就会因 `node:fs` 之类的裸模块报错中止，而
+ * tree-shaking 帮不上忙 —— 解析先于摇树。所以：
+ *
+ * - Node 侧（读文件）实现放 `loadWasm.ts`；
+ * - 浏览器侧（fetch）实现放 `loadWasm.browser.ts`；
+ * - 由 package.json 的 `browser` 字段在打包时做文件替换；
+ * - **本文件两者共用，且零 `node:*` 引用**。
+ */
+/** 算法白名单：确保非法 `name` 在到达文件系统 / 网络前被拒绝。 */
+const WASM_ALGOS = ['sm2', 'sm3', 'sm4', 'sm9', 'zuc'];
+export function isWasmAlgo(name) {
+    return typeof name === 'string' && WASM_ALGOS.includes(name);
+}
+export function rejectBadName(name) {
+    const got = typeof name === 'string' ? `"${name}"` : typeof name;
+    throw new RangeError(`loadWasm: 未知算法 ${got}，期望 ${WASM_ALGOS.map((a) => `"${a}"`).join(' | ')}`);
+}
+/** ASC 默认产物会导入 `env` 模块（abort / trace / __assert_fail）。 */
+export const ASC_ENV = {
+    env: {
+        abort: () => {
+            throw new Error('wasm: abort');
+        },
+        trace: () => { },
+        __assert_fail: () => {
+            throw new Error('wasm: assert_fail');
+        },
+    },
+};
+/**
+ * 同步实例化 wasm。失败抛 WebAssembly 自身的 CompileError / LinkError。
+ *
+ * @param buf wasm 字节。
+ */
+export function instantiateFromBuffer(buf) {
+    const mod = new WebAssembly.Module(buf);
+    const inst = new WebAssembly.Instance(mod, ASC_ENV);
+    const exports = inst.exports;
+    const memory = exports.memory ?? new WebAssembly.Memory({ initial: 1 });
+    return Object.freeze({ exports, memory });
+}
+/** 模块缓存。key = 算法名，value = 已 memoize 的 Promise。 */
+const cache = new Map();
+/**
+ * 按算法名记忆化加载：同名的第二次调用复用第一次的 Promise，并发安全
+ * （不会重复 instantiate）。
+ *
+ * @param name 算法名（调用方已校验）。
+ * @param loader 实际取字节 + 实例化的实现（Node / 浏览器各不相同）。
+ */
+export function memoizeLoad(name, loader) {
+    let p = cache.get(name);
+    if (!p) {
+        p = loader(name);
+        cache.set(name, p);
+    }
+    return p;
+}
+/**
+ * 清空缓存。仅供测试使用 —— 单元测试需要测并发安全场景时必须能重置状态。
+ */
+export function resetCacheForTests() {
+    cache.clear();
+}

package/dist/runtime/loadWasm.d.ts

@@ -1,31 +1,21 @@
 /**
- * 跨运行时 WASM 加载器（runtime WASM loader）。
+ * WASM 加载器（**Node 版**）。
  *
- * 支持三种环境：
- * - Node.js 18+：通过 `node:fs/promises` 读取构建产物 `dist/<name>/<name>.wasm`。
- * - 现代浏览器（Vite/Webpack/Rollup）：用 `fetch(new URL(...))`，由打包器解析资源 URL。
- * - Deno/Bun：自动复用 Node 路径（都暴露 `node:fs`）。
+ * 浏览器打包时，本文件会被 `loadWasm.browser.ts` 替换（package.json 的 `browser`
+ * 字段）—— 因为这里的 `node:fs` / `node:path` / `node:url` 会让 Webpack / esbuild /
+ * Rspack 在解析期直接构建失败。共享逻辑（类型、实例化、记忆化）在
+ * `loadWasm.core.ts`。**不要在 core 或 browser 版里 import 本文件。**
  *
  * 设计要点：
- * - **按算法名称记忆化（memoization）**：同一个 `name` 在并发调用下只实例化一次。
- *   缓存键为 `WasmAlgo`，值为 `Promise<WasmModule>`；第一个调用挂上 Promise，
- *   后续调用拿到同一引用。Review-Focus #7 明确要求"并发调用拿到同一模块"。
- * - **同步 / 异步并存**：业务 API 大量使用同步入口（见 spec §12.1 Q2），
- *   但 WASM 加载必须异步；这里同时提供 `loadWasm`（async）与 `loadWasmSync`
- *   （Node 专用），后者内部用 `fs.readFileSync` + `WebAssembly.Module`。
- * - **内存视图返回**：所有从 WASM 内存取出的字节都用 `slice()` 返回拷贝，
- *   绝不让上层持有会因内存增长而失效的视图。Review-Focus #8。
- *
- * spec/plan 对应：plan Task 1；spec §7 跨运行时、§10 测试。
+ * - **按算法名称记忆化**：同名在并发调用下只实例化一次（见 core 的 `memoizeLoad`）。
+ * - **同步 / 异步并存**：业务 API 大量使用同步入口，但 WASM 加载必须异步；
+ *   这里同时提供 `loadWasm`（async）与 `loadWasmSync`（Node 专用，
+ *   每次独立读文件 + instantiate，与异步版不共享实例）。
+ * - **内存视图返回**：所有从 WASM 内存取出的字节都由上层 `slice()` 拷贝，
+ *   绝不让上层持有会因内存增长而失效的视图。
  */
-/** 算法白名单：确保非法 `name` 在到达文件系统 / 浏览器分支前被拒绝。 */
-declare const WASM_ALGOS: readonly ['sm2', 'sm3', 'sm4', 'sm9', 'zuc'];
-export type WasmAlgo = (typeof WASM_ALGOS)[number];
-/** 加载完成后的 WASM 模块封装。`exports` 已类型化为 `WebAssembly.Exports`。 */
-export interface WasmModule {
-    readonly exports: WebAssembly.Exports;
-    readonly memory: WebAssembly.Memory;
-}
+import { type WasmAlgo, type WasmModule } from './loadWasm.core.js';
+export type { WasmAlgo, WasmModule } from './loadWasm.core.js';
 /**
  * 异步加载并实例化 wasm。**这是业务代码的主入口**。
  *
@@ -36,10 +26,10 @@ export interface WasmModule {
  */
 export declare function loadWasm(name: WasmAlgo): Promise<WasmModule>;
 /**
- * 同步加载 wasm（Node 专用）。浏览器路径不可用，会抛错。
+ * 同步加载 wasm（**Node 专用**）。浏览器路径不可用，会抛错。
  *
- * 用法：在应用启动时先 `await loadWasm('sm3')` 预热缓存，之后业务函数
- * 调用 `loadWasmSync('sm3')` 即可零开销获取引用。
+ * 每次调用独立读文件 + instantiate，**不**复用 `loadWasm` 的缓存实例
+ * （Node 的 Promise 无法被同步等待）。
  *
  * @param name 算法名。
  * @returns 冻结的 WasmModule。
@@ -55,4 +45,3 @@ export declare function getCachedWasm(name: WasmAlgo): Promise<WasmModule>;
  * 清空缓存。仅供测试使用 —— 单元测试需要测并发安全场景时必须能重置状态。
  */
 export declare function _resetCacheForTests(): void;
-export {};

package/dist/runtime/loadWasm.js

@@ -1,36 +1,24 @@
 /**
- * 跨运行时 WASM 加载器（runtime WASM loader）。
+ * WASM 加载器（**Node 版**）。
  *
- * 支持三种环境：
- * - Node.js 18+：通过 `node:fs/promises` 读取构建产物 `dist/<name>/<name>.wasm`。
- * - 现代浏览器（Vite/Webpack/Rollup）：用 `fetch(new URL(...))`，由打包器解析资源 URL。
- * - Deno/Bun：自动复用 Node 路径（都暴露 `node:fs`）。
+ * 浏览器打包时，本文件会被 `loadWasm.browser.ts` 替换（package.json 的 `browser`
+ * 字段）—— 因为这里的 `node:fs` / `node:path` / `node:url` 会让 Webpack / esbuild /
+ * Rspack 在解析期直接构建失败。共享逻辑（类型、实例化、记忆化）在
+ * `loadWasm.core.ts`。**不要在 core 或 browser 版里 import 本文件。**
  *
  * 设计要点：
- * - **按算法名称记忆化（memoization）**：同一个 `name` 在并发调用下只实例化一次。
- *   缓存键为 `WasmAlgo`，值为 `Promise<WasmModule>`；第一个调用挂上 Promise，
- *   后续调用拿到同一引用。Review-Focus #7 明确要求"并发调用拿到同一模块"。
- * - **同步 / 异步并存**：业务 API 大量使用同步入口（见 spec §12.1 Q2），
- *   但 WASM 加载必须异步；这里同时提供 `loadWasm`（async）与 `loadWasmSync`
- *   （Node 专用），后者内部用 `fs.readFileSync` + `WebAssembly.Module`。
- * - **内存视图返回**：所有从 WASM 内存取出的字节都用 `slice()` 返回拷贝，
- *   绝不让上层持有会因内存增长而失效的视图。Review-Focus #8。
- *
- * spec/plan 对应：plan Task 1；spec §7 跨运行时、§10 测试。
+ * - **按算法名称记忆化**：同名在并发调用下只实例化一次（见 core 的 `memoizeLoad`）。
+ * - **同步 / 异步并存**：业务 API 大量使用同步入口，但 WASM 加载必须异步；
+ *   这里同时提供 `loadWasm`（async）与 `loadWasmSync`（Node 专用，
+ *   每次独立读文件 + instantiate，与异步版不共享实例）。
+ * - **内存视图返回**：所有从 WASM 内存取出的字节都由上层 `slice()` 拷贝，
+ *   绝不让上层持有会因内存增长而失效的视图。
  */
-import { existsSync, readFile, readFileSync } from 'node:fs';
-import { readFile as readFileAsync } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-/** 算法白名单：确保非法 `name` 在到达文件系统 / 浏览器分支前被拒绝。 */
-const WASM_ALGOS = ['sm2', 'sm3', 'sm4', 'sm9', 'zuc'];
-function isWasmAlgo(name) {
-    return typeof name === 'string' && WASM_ALGOS.includes(name);
-}
-function rejectBadName(name) {
-    const got = typeof name === 'string' ? `"${name}"` : typeof name;
-    throw new RangeError(`loadWasm: 未知算法 ${got}，期望 ${WASM_ALGOS.map((a) => `"${a}"`).join(' | ')}`);
-}
+import * as nodeFs from 'node:fs';
+import * as nodeFsPromises from 'node:fs/promises';
+import * as nodePath from 'node:path';
+import * as nodeUrl from 'node:url';
+import { instantiateFromBuffer, isWasmAlgo, memoizeLoad, rejectBadName, resetCacheForTests, } from './loadWasm.core.js';
 /** 当前是否在 Node 进程内。CI / Vite SSR / 真浏览器都据此切换加载路径。 */
 const isNode = typeof process !== 'undefined' && !!process.versions?.node;
 /**
@@ -47,18 +35,18 @@ function wasmPath(name) {
     // 1. cwd/dist（开发/单仓根目录模式）。这是首选路径；日志里
     // 见到 "src/<name>/<name>.wasm" 即说明回退路径被命中，提示开发模式
     // 下应当先 `pnpm build:wasm:<name>`。
-    const cwdPath = resolve(process.cwd(), 'dist', name, `${name}.wasm`);
-    if (existsSync(cwdPath))
+    const cwdPath = nodePath.resolve(process.cwd(), 'dist', name, `${name}.wasm`);
+    if (nodeFs.existsSync(cwdPath))
         return cwdPath;
     // 2. 源文件相对路径（生产产物 dist/runtime/loadWasm.js → ../<name>/<name>.wasm）。
     let here;
     try {
-        here = dirname(fileURLToPath(import.meta.url));
+        here = nodePath.dirname(nodeUrl.fileURLToPath(import.meta.url));
     }
     catch {
         here = process.cwd();
     }
-    return resolve(here, '..', name, `${name}.wasm`);
+    return nodePath.resolve(here, '..', name, `${name}.wasm`);
 }
 /**
  * 异步读取 wasm 字节（Node 路径）。
@@ -67,7 +55,7 @@ function wasmPath(name) {
  * @returns wasm 二进制 ArrayBuffer；总是一个**拷贝**，不持有 fd 缓存。
  */
 async function nodeReadWasm(name) {
-    const buf = await readFileAsync(wasmPath(name));
+    const buf = await nodeFsPromises.readFile(wasmPath(name));
     return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 }
 /**
@@ -77,53 +65,9 @@ async function nodeReadWasm(name) {
  * @returns wasm 二进制 ArrayBuffer。
  */
 function nodeReadWasmSync(name) {
-    const buf = readFileSync(wasmPath(name));
+    const buf = nodeFs.readFileSync(wasmPath(name));
     return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 }
-/**
- * 抽象出"按当前环境读 wasm 字节"。
- *
- * @param name 算法名。
- * @returns ArrayBuffer 形式的 wasm 字节。
- */
-async function loadArrayBuffer(name) {
-    if (isNode)
-        return nodeReadWasm(name);
-    // 浏览器：用 import.meta.url 解析同级 wasm 资源；打包器负责重写 URL。
-    const url = new URL(`../${name}/${name}.wasm`, import.meta.url);
-    const res = await fetch(url);
-    if (!res.ok) {
-        throw new Error(`loadWasm: failed to fetch ${url}: ${res.status} ${res.statusText}`);
-    }
-    return res.arrayBuffer();
-}
-/** ASC 默认产物会导入 `env` 模块（abort / trace / __assert_fail）。
- *  这些 stub 与 `loadWasm` 异步路径一致；统一到模块级常量以便 sync/async 共享。 */
-const ASC_ENV = {
-    env: {
-        abort: () => {
-            throw new Error('wasm: abort');
-        },
-        trace: () => { },
-        __assert_fail: () => {
-            throw new Error('wasm: assert_fail');
-        },
-    },
-};
-/**
- * 同步实例化 wasm（仅 Node）。失败抛 WebAssembly 自身的 CompileError / LinkError。
- *
- * @param buf wasm 字节。
- */
-function instantiateFromBuffer(buf) {
-    const mod = new WebAssembly.Module(buf);
-    const inst = new WebAssembly.Instance(mod, ASC_ENV);
-    const exports = inst.exports;
-    const memory = exports.memory ?? new WebAssembly.Memory({ initial: 1 });
-    return Object.freeze({ exports, memory });
-}
-/** 模块缓存。key = 算法名，value = 已 memoize 的 Promise。 */
-const cache = new Map();
 /**
  * 异步加载并实例化 wasm。**这是业务代码的主入口**。
  *
@@ -135,21 +79,13 @@ const cache = new Map();
 export function loadWasm(name) {
     if (!isWasmAlgo(name))
         rejectBadName(name);
-    let p = cache.get(name);
-    if (!p) {
-        p = (async () => {
-            const buf = await loadArrayBuffer(name);
-            return instantiateFromBuffer(buf);
-        })();
-        cache.set(name, p);
-    }
-    return p;
+    return memoizeLoad(name, async (n) => instantiateFromBuffer(await nodeReadWasm(n)));
 }
 /**
- * 同步加载 wasm（Node 专用）。浏览器路径不可用，会抛错。
+ * 同步加载 wasm（**Node 专用**）。浏览器路径不可用，会抛错。
  *
- * 用法：在应用启动时先 `await loadWasm('sm3')` 预热缓存，之后业务函数
- * 调用 `loadWasmSync('sm3')` 即可零开销获取引用。
+ * 每次调用独立读文件 + instantiate，**不**复用 `loadWasm` 的缓存实例
+ * （Node 的 Promise 无法被同步等待）。
  *
  * @param name 算法名。
  * @returns 冻结的 WasmModule。
@@ -160,8 +96,7 @@ export function loadWasmSync(name) {
     }
     if (!isWasmAlgo(name))
         rejectBadName(name);
-    const buf = nodeReadWasmSync(name);
-    return instantiateFromBuffer(buf);
+    return instantiateFromBuffer(nodeReadWasmSync(name));
 }
 /**
  * 获取已缓存的 wasm 引用（若无则初始化）。等价于 `loadWasm`，提供语义化别名。
@@ -175,7 +110,5 @@ export function getCachedWasm(name) {
  * 清空缓存。仅供测试使用 —— 单元测试需要测并发安全场景时必须能重置状态。
  */
 export function _resetCacheForTests() {
-    cache.clear();
+    resetCacheForTests();
 }
-// 引用 readFile 以避免被 unused 误删（运行时仅在动态分支用到）。
-void readFile;

package/dist/runtime/random.browser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 宿主随机数包装（**浏览器版**）。
+ *
+ * 打包时由 package.json 的 `browser` 字段替换 `random.js`。存在的唯一理由是：
+ * `node:crypto` 会让 Webpack 5 / esbuild / Rspack 在解析期构建失败。
+ * 与宿主无关的拒绝采样逻辑在 `random.core.ts`。本文件**零 `node:*` 引用**。
+ *
+ * 安全姿态与 Node 版一致：**只认 `globalThis.crypto`，取不到就抛错
+ * （fail-closed），绝不降级到非密码学随机源。**
+ */
+/**
+ * 取 `n` 字节 CSPRNG 随机数。
+ *
+ * @param n 字节数，范围 `[0, 65536]`（WebCrypto `getRandomValues` 的规范上限）。
+ * @returns 新分配的字节数组（拷贝）。
+ * @throws RangeError n 不在范围内或不是整数。
+ */
+export declare function randomBytes(n: number): Uint8Array;
+/**
+ * 在 `[1, order)` 区间均匀取一个随机标量（用于 SM2 / SM9 椭圆曲线 k）。
+ *
+ * @param order 椭圆曲线子群阶（如 SM2 的 n、SM9 的 BN256 n）。
+ * @returns 满足 `1 ≤ k < order` 的大整数。
+ */
+export declare function randomScalarBelow(order: bigint): bigint;