hd-wallet-wasm 2.1.2 → 2.1.3

package/dist/runtime/index.mjs

@@ -9,7 +9,7 @@
  * - Transaction building and signing
  *
  * @module hd-wallet-wasm
- * @version 2.1.2
+ * @version 2.1.3
  */
 
 // Import aligned API for batch operations
@@ -1342,6 +1342,59 @@ export async function computeWasmHash(wasmBytes) {
   return bytesToHex(wallet.utils.sha256(bytes));
 }
 
+/**
+ * ONE WALLET INSTANCE PER REALM AND VERSION.
+ *
+ * A page can hold several copies of this file: the site runtime
+ * (/wallet-wasm/runtime/index.mjs), a bundler's copy inside an app chunk and
+ * another inside sdn-js. Each used to instantiate its own WASM, and every
+ * instance commits its own linear memory. The first init() of a version now
+ * instantiates it and publishes the promise on a realm-global keyed by the
+ * package version, so every copy of the same version in the realm shares
+ * that one instance (each copy keeps its own JS wrapper over it). A different
+ * version never shares: its exports may differ.
+ */
+const PACKAGE_VERSION = '2.1.3';
+const REALM_INSTANCES = Symbol.for('hd-wallet-wasm/realm-instances');
+
+function realmInstances() {
+  const existing = globalThis[REALM_INSTANCES];
+  if (existing && typeof existing === 'object') return existing;
+  const created = Object.create(null);
+  Object.defineProperty(globalThis, REALM_INSTANCES, {
+    value: created,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+  return created;
+}
+
+function sharedWasmModule() {
+  const instances = realmInstances();
+  let pending = instances[PACKAGE_VERSION];
+  if (!pending) {
+    pending = loadWasmModule();
+    instances[PACKAGE_VERSION] = pending;
+    // A failed load is not cached: the next init() tries again.
+    pending.catch(() => {
+      if (instances[PACKAGE_VERSION] === pending) delete instances[PACKAGE_VERSION];
+    });
+  }
+  return pending;
+}
+
+/**
+ * A SHORT-LIVED INSTANCE for the password KDF (scrypt dirties 64 MiB, and a
+ * WASM memory never shrinks). It is never shared or published: the caller
+ * moves the derived identity into the realm's instance (sdn-typed.mjs,
+ * identity transfer), zeroes this instance's whole memory and drops it, so
+ * the collector releases the memory.
+ */
+function createKdfInstance() {
+  return loadWasmModule();
+}
+
 /**
  * WASM module loader (single-file, isomorphic)
  * @returns {Promise<Object>} Initialized WASM module
@@ -5192,7 +5245,7 @@ function createModule(wasm) {
   };
 
   Object.defineProperty(module, 'sdn', {
-    value: createSdnTypedCapabilities(wasm),
+    value: createSdnTypedCapabilities(wasm, { createKdfInstance }),
     enumerable: true,
     writable: false,
     configurable: false,
@@ -5337,9 +5390,14 @@ export const WellKnownCoinType = Object.freeze({
  * Initialize the HD Wallet WASM module
  * @returns {Promise<Object>} Initialized HDWalletModule
  */
+let realmModule = null;
 export default async function init() {
-  const wasm = await loadWasmModule();
-  return createModule(wasm);
+  // One wrapper per copy of this file, over the realm's one instance.
+  if (!realmModule) {
+    realmModule = sharedWasmModule().then(createModule);
+    realmModule.catch(() => { realmModule = null; });
+  }
+  return realmModule;
 }
 
 /**

package/dist/runtime/sdn-typed.mjs

@@ -38,9 +38,20 @@ const RAW_ENTRYPOINTS = Object.freeze([
   '_hd_sdn_sign_asset_review_authority_activation',
   '_hd_sdn_sign_asset_review_decision',
   '_hd_sdn_seal_remembered_identity',
+  '_hd_sdn_transfer_begin',
+  '_hd_sdn_transfer_seal',
+  '_hd_sdn_transfer_open',
   '_hd_sdn_destroy_identity',
 ]);
 
+const TRANSFER_PUBLIC_KEY_BYTES = 32;
+const MAX_TRANSFER_BYTES = 1024;
+
+// Each capabilities object's transfer sealer, reachable only from this file:
+// sealing is never a public capability (it would hand out a seed sealed to
+// any key a caller names).
+const transferSealers = new WeakMap();
+
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder('utf-8', { fatal: true });
 const SafeUint8Array = Uint8Array;
@@ -528,7 +539,13 @@ function readRequired(scope, pointer) {
  * Internal per-WASM-instance factory. This is intentionally not a package
  * export subpath; the wallet-origin wrapper constructs it inside createModule.
  */
-export function createSdnTypedCapabilities(wasm) {
+export function createSdnTypedCapabilities(wasm, options = {}) {
+  // createKdfInstance (index.mjs) makes a fresh, unshared WASM instance: the
+  // password KDF runs there and the identity is moved into `wasm`.
+  const createKdfInstance = isObject(options) &&
+    typeof options.createKdfInstance === 'function'
+    ? options.createKdfInstance
+    : null;
   if (!isObject(wasm) || typeof wasm._malloc !== 'function' ||
       typeof wasm._free !== 'function' ||
       RAW_ENTRYPOINTS.some((name) => typeof wasm[name] !== 'function')) {
@@ -658,6 +675,108 @@ export function createSdnTypedCapabilities(wasm) {
     }
   }
 
+  // THE RECEIVER: a fresh X25519 key in this instance (native randomness);
+  // only its public half comes back. Its private half stays native for one open.
+  function beginTransfer() {
+    const scope = createAllocationScope(wasm);
+    try {
+      const out = scope.allocate(TRANSFER_PUBLIC_KEY_BYTES);
+      let status;
+      try {
+        status = wasm._hd_sdn_transfer_begin(out, TRANSFER_PUBLIC_KEY_BYTES);
+      } catch {
+        fail('CRYPTO_FAILURE');
+      }
+      if (status !== 0) throwStatus(status);
+      return scope.bytes(out, TRANSFER_PUBLIC_KEY_BYTES);
+    } finally {
+      if (scope.cleanup()) fail('CRYPTO_FAILURE');
+    }
+  }
+
+  // THE SENDER: this instance's identity sealed to the receiver's public key.
+  function sealTransfer(handle, recipientPublic) {
+    const record = recordFor(handle);
+    const scope = createAllocationScope(wasm);
+    try {
+      const recipient = scope.allocate(recipientPublic);
+      const outRequired = scope.allocate(4);
+      const outBytes = scope.allocate(MAX_TRANSFER_BYTES);
+      let status;
+      try {
+        status = wasm._hd_sdn_transfer_seal(
+          record.nativeValue, recipient, recipientPublic.length,
+          outBytes, MAX_TRANSFER_BYTES, outRequired,
+        );
+      } catch {
+        fail('CRYPTO_FAILURE');
+      }
+      if (status !== 0) throwStatus(status);
+      const required = readRequired(scope, outRequired);
+      if (required <= TRANSFER_PUBLIC_KEY_BYTES || required > MAX_TRANSFER_BYTES) {
+        fail('CRYPTO_FAILURE');
+      }
+      return scope.bytes(outBytes, required);
+    } finally {
+      if (scope.cleanup()) fail('CRYPTO_FAILURE');
+    }
+  }
+
+  /**
+   * THE PASSWORD KDF IN A SHORT-LIVED INSTANCE. scrypt (password-scrypt-v2)
+   * dirties 64 MiB, and a WASM memory never shrinks, so deriving here would
+   * keep 64 MiB committed for the session. Instead: a fresh instance derives,
+   * its identity moves into this one (seed sealed native-to-native: only
+   * public keys and sealed bytes pass through JS), the fresh instance's
+   * identity is destroyed, its whole memory is zeroed and it is dropped.
+   * Nothing awaits between begin, seal and open, so no other transfer can
+   * interleave.
+   */
+  async function deriveInKdfInstance(derive, expectedAccountIndex) {
+    let kdfWasm;
+    try {
+      kdfWasm = await createKdfInstance();
+    } catch {
+      fail('CRYPTO_FAILURE');
+    }
+    let kdf;
+    let derived;
+    try {
+      kdf = createSdnTypedCapabilities(kdfWasm);
+      derived = await derive(kdf);
+      const recipient = beginTransfer();
+      const sealed = transferSealers.get(kdf)(derived.handle, recipient);
+      const opened = invokeDerive(
+        '_hd_sdn_transfer_open',
+        ([sealedPointer]) => [sealedPointer, sealed.length],
+        [{ bytes: sealed }],
+        'sdn-bip32-slip10-purpose-v1',
+        'password-scrypt-v2',
+        expectedAccountIndex,
+        () => wipeAll([sealed]),
+      );
+      if (JSON.stringify(opened.identity) !== JSON.stringify(derived.identity)) {
+        capabilities.destroySdnIdentity(opened.handle);
+        fail('CRYPTO_FAILURE');
+      }
+      return opened;
+    } finally {
+      try {
+        if (derived) kdf.destroySdnIdentity(derived.handle);
+      } catch {
+        // The memory is zeroed below either way.
+      }
+      try {
+        const heap = checkedHeap(kdfWasm);
+        new SafeUint8Array(heap.buffer).fill(0);
+      } catch {
+        // Nothing else holds the instance; the collector still releases it.
+      }
+      kdf = null;
+      kdfWasm = null;
+    }
+  }
+
   const capabilities = {
     async derivePasswordIdentity(input) {
       let callerPassword;
@@ -671,6 +790,13 @@ export function createSdnTypedCapabilities(wasm) {
         if (username.length > MAX_MODERN_CREDENTIAL_BYTES) fail('INVALID_USERNAME');
         if (password.length > MAX_MODERN_CREDENTIAL_BYTES) fail('INVALID_PASSWORD');
         const account = requireAccount(input.accountIndex);
+        if (createKdfInstance) {
+          return await deriveInKdfInstance((kdf) => kdf.derivePasswordIdentity({
+            usernameUtf8: username,
+            passwordUtf8: password,
+            accountIndex: account,
+          }), account);
+        }
         return invokeDerive(
           '_hd_sdn_derive_password_identity',
           ([usernamePointer, passwordPointer]) => [
@@ -978,5 +1104,7 @@ export function createSdnTypedCapabilities(wasm) {
     },
   };
 
-  return Object.freeze(capabilities);
+  const frozen = Object.freeze(capabilities);
+  transferSealers.set(frozen, sealTransfer);
+  return frozen;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-wallet-wasm",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "Comprehensive HD Wallet implementation in WebAssembly - BIP-32/39/44, multi-curve, multi-chain support",
   "type": "module",
   "main": "./dist/runtime/index.mjs",
@@ -92,5 +92,5 @@
   "devDependencies": {
     "@types/node": "^20.0.0"
   },
-  "gitHead": "e862d42fcf505cdbc7e928d676bc1a180a167989"
+  "gitHead": "226dfe7527fcb54571b745ad9f3ebc0b6cc51898"
 }