@ethernity-cloud/sdk-js 1.2.0 → 1.5.0

package/init.js

@@ -72,6 +72,53 @@ const promptOptions = (message, options, defaultOption) => {
   });
 };
 
+// Opt-in Enclave State Registry step (ESR RFC §8). Skippable; defaults to off,
+// so a project that never answers yes behaves exactly as it did before ESR.
+// Env equivalents for unattended runs (RFC §9): ECLD_ESR_ENABLE,
+// ECLD_ESR_CONTRACT. Values are persisted to .env, which is how this SDK
+// carries project settings (the Python SDK uses .config.json for the same job).
+const configureEsr = async () => {
+  const enableEnv = process.env.ECLD_ESR_ENABLE;
+  let enabled;
+  if (enableEnv !== undefined) {
+    enabled = /^(1|true|yes|y|on)$/i.test(String(enableEnv).trim());
+    console.log(
+      `Enable Enclave State Registry? [ECLD_ESR_ENABLE -> ${enabled ? "yes" : "no"}]`,
+    );
+  } else {
+    const answer = await promptOptions(
+      "Enable Enclave State Registry (persistent on-chain state)? (default is no): ",
+      ["yes", "no"],
+      "no",
+    );
+    enabled = answer === "yes";
+  }
+
+  if (!enabled) {
+    // Only write an explicit disable when the env var asked for it; re-running
+    // init must not silently switch off a previously configured ESR.
+    if (enableEnv !== undefined) writeEnv("ESR_ENABLED", "false");
+    return;
+  }
+
+  let address = process.env.ECLD_ESR_CONTRACT;
+  if (address === undefined) {
+    address = await new Promise((resolve) =>
+      rl.question("ESR registry contract address (0x...): ", resolve),
+    );
+  }
+  address = String(address || "").trim();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+    console.error(`ERROR: ESR contract address ${JSON.stringify(address)} is not a valid address.`);
+    console.error("       Set a valid 0x… address (ECLD_ESR_CONTRACT) and re-run ecld-init.");
+    process.exit(1);
+  }
+
+  writeEnv("ESR_ENABLED", "true");
+  writeEnv("ESR_CONTRACT_ADDRESS", address);
+  console.log(`ESR enabled: contract ${address}`);
+};
+
 const printIntro = () => {
   const intro = `
     ╔───────────────────────────────────────────────────────────────────────────────────────────────────────────────╗
@@ -302,6 +349,8 @@ const main = async () => {
 
   writeEnv("BLOCKCHAIN_NETWORK", blockchainNetwork.replace(/ /g, "_"));
   writeEnv("IPFS_ENDPOINT", customUrl);
+  console.log();
+  await configureEsr();
   writeEnv("IPFS_TOKEN", ipfsToken || "");
   writeEnv("VERSION", "v1");
   console.log();

package/nodenithy/build/securelock/Dockerfile.tmpl

@@ -15,6 +15,11 @@ ENV IMAGE_REGISTRY_ADDRESS=__IMAGE_REGISTRY_ADDRESS__
 ENV RPC_URL=__RPC_URL__
 ENV CHAIN_ID=__CHAIN_ID__
 ENV TRUSTED_ZONE_IMAGE=__TRUSTED_ZONE_IMAGE__
+# ESR (RFC §5.4): rendered by build.mjs to `ENV ESR_CONTRACT_ADDRESS=0x...` only
+# when ESR is enabled, and to nothing otherwise -- so non-ESR images keep exactly
+# the layer content (and MRENCLAVE) they had before ESR existed. The securelock
+# gates all ESR behaviour on this variable being non-empty.
+__ESR_ENV__
 
 RUN mkdir binary-fs-dir
 

package/nodenithy/build/securelock/src/README-keygen.md

@@ -0,0 +1,41 @@
+# SGX key-gen module (`sgx_report.node`)
+
+The JS SDK ships this module **only as a prebuilt N-API addon**
+(`sgx_report.node`) — never the C source (`get_sgx_report.c`,
+`sgx_report_napi.c`). The identity-key derivation (SGX EREPORT + obfuscated
+MR_SIGNER + HKDF-SHA512 domain-separated derivation) lives entirely in the
+compiled binary, so a developer inspecting the package or build tree never sees
+the algorithm. `get_sgx_report.c` and `sgx_report_napi.c` are gitignored here
+so they can never be committed.
+
+## Where the source lives
+
+The source of truth is the runtime repo, not this package:
+
+- `etny-nodenithy` → `v3/build/{securelock,trustedzone,validator}/src/`
+  (`get_sgx_report.c` + `sgx_report_napi.c`)
+
+## How the `.node` is produced
+
+`sgx_report.node` is a **build artifact of the etny-nodenithy pipeline** — its
+Dockerfile compiles `sgx_report_napi.c` (which `#include`s `get_sgx_report.c`)
+into the addon with a single gcc command against node's `node_api.h`. To refresh
+the copy the SDK ships, take the `sgx_report.node` that pipeline produces and
+commit it here as `securelock/src/sgx_report.node`.
+
+The JS wrappers `sgx_report.js` (loader) and `self_sign.js` (calls
+`deriveIdentityScalar`) ship as source — they contain no algorithm, only calls
+into the addon.
+
+## Why not compile it in the SDK build
+
+The securelock Dockerfile bakes `src/` into binary-fs but does **not** compile
+the addon, so the SDK must carry the prebuilt `.node`. `build.mjs` fails fast if
+`src/sgx_report.node` is missing.
+
+## Honest scope
+
+This hides the SOURCE, not the algorithm: the `.node` still contains the
+executable logic and the enclave image is public. On testnet (no attestation)
+the derived key is reproducible by anyone who runs the image. Key exclusivity
+comes from attestation, not from shipping only the binary.

package/nodenithy/build/securelock/src/ecld_state.js

@@ -0,0 +1,304 @@
+// Enclave State Registry (ESR) — in-enclave state API (Nodenithy).
+//
+// Gives payload code durable, encrypted state across tasks:
+//
+//     const { StateRegistry } = require('./ecld_state');
+//     const state = new StateRegistry();
+//     await state.commit('my-key', (s) => ({ ...s, n: (s.n || 0) + 1 }));
+//
+// State is encrypted inside the enclave, stored as an IPFS object, and only a
+// POINTER (the CID) plus a version goes on-chain. The registry keeps one entry
+// per (enclave, key) with monotonic versions and optimistic concurrency.
+//
+// ## Why the enclave computes the CID itself
+//
+// The node is untrusted. If it told the enclave which CID to commit, a
+// malicious operator could pin the enclave's blob but return the CID of
+// DIFFERENT content; the enclave would sign that onto the chain, and clients
+// would fetch attacker-chosen state believing the enclave authored it.
+//
+// A CID is a hash of the content, so the enclave derives it from the bytes it
+// just encrypted (CIDv1/raw = base32(0x01 0x55 0x12 0x20 || sha256(content)))
+// and commits that. The node pins and verifies but never chooses. It also means
+// the enclave never waits on the node: it writes the blob, writes the CID,
+// commits, and moves on.
+//
+// ## Encryption
+//
+// State is encrypted with a key derived from the enclave identity under a
+// SECOND domain separator (distinct from the ESR wallet's), so the state key
+// cannot collide with the wallet key. State therefore inherits exactly the
+// identity's security: enclave-only on mainnet, reproducible on testnet — which
+// is the accepted testnet posture (functional testing, not secrecy).
+//
+// SECURITY: the state key and the wallet key never leave this module. Only the
+// address and the CID are ever emitted.
+const crypto = require('crypto');
+const { ethers } = require('ethers');
+const esr_wallet = require('./esr_wallet');
+
+const DOMAIN_SEP_STATE = 'ethernity-cloud/esr-encryption/v1';
+
+// AES-GCM parameters, pinned explicitly so the blob layout never depends on a
+// library default: nonce(12) || tag(16) || ciphertext.
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+
+let _identityPriv = null;
+let _swift = null;
+let _bucket = null;
+let _contractAddress = null;
+let _provider = null;
+
+/**
+ * Wire the registry to the enclave's identity, storage and chain access.
+ * Called by securelock at task start; payload code never calls this.
+ */
+function configure({ identityPriv, swiftStreamService, bucket, contractAddress, provider }) {
+  _identityPriv = identityPriv;
+  _swift = swiftStreamService;
+  _bucket = bucket;
+  _contractAddress = contractAddress;
+  _provider = provider;
+}
+
+function keccak256(buf) {
+  return Buffer.from(ethers.utils.keccak256(buf).slice(2), 'hex');
+}
+
+/**
+ * AES key for state, derived under its own domain separator. A separate
+ * separator from the wallet's means the two keys are provably unrelated:
+ * compromising one does not yield the other.
+ */
+function stateKey() {
+  if (!_identityPriv) {
+    throw new Error('StateRegistry is not configured (no enclave identity)');
+  }
+  const material = Buffer.isBuffer(_identityPriv)
+    ? _identityPriv
+    : Buffer.from(String(_identityPriv), 'utf8');
+  return keccak256(Buffer.concat([Buffer.from(DOMAIN_SEP_STATE, 'utf8'), material]));
+}
+
+/**
+ * CIDv1/raw/sha2-256 for `content`, computed without touching IPFS.
+ * Matches `ipfs add --cid-version=1 --raw-leaves`, which is what lets the
+ * enclave commit a CID it derived itself rather than one a node handed it.
+ */
+function cidv1Raw(content) {
+  const digest = crypto.createHash('sha256').update(content).digest();
+  const raw = Buffer.concat([Buffer.from([0x01, 0x55, 0x12, 0x20]), digest]);
+  return 'b' + base32Encode(raw).toLowerCase().replace(/=+$/, '');
+}
+
+// RFC4648 base32, no padding stripped here (the caller strips it).
+function base32Encode(buf) {
+  const A = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+  let bits = 0;
+  let value = 0;
+  let out = '';
+  for (const byte of buf) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += A[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += A[(value << (5 - bits)) & 31];
+  return out;
+}
+
+/**
+ * True only for values shaped like an IPFS CID.
+ *
+ * The contract accepts any non-empty string as the pointer, so a buggy writer
+ * can commit something that is not a CID (the live registry holds one 0x…
+ * digest). That is a defect in the writer, not a supported format: such an
+ * entry is rejected rather than fetched, because passing it on means an error
+ * at best and a retry-loop at worst.
+ */
+function looksLikeCID(value) {
+  const cid = (value || '').trim();
+  if (!cid || cid.startsWith('0x')) return false;
+  if (cid.startsWith('Qm') && cid.length === 46) return true;
+  if (cid.startsWith('b') && cid.length >= 46 && cid === cid.toLowerCase()) return true;
+  return false;
+}
+
+function encrypt(plaintext) {
+  const nonce = crypto.randomBytes(NONCE_LEN);
+  const cipher = crypto.createCipheriv('aes-256-gcm', stateKey(), nonce, {
+    authTagLength: TAG_LEN
+  });
+  const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return Buffer.concat([nonce, cipher.getAuthTag(), ct]);
+}
+
+function decrypt(blob) {
+  if (blob.length < NONCE_LEN + TAG_LEN) {
+    throw new Error('state blob is too short to be valid');
+  }
+  const nonce = blob.subarray(0, NONCE_LEN);
+  const tag = blob.subarray(NONCE_LEN, NONCE_LEN + TAG_LEN);
+  const ct = blob.subarray(NONCE_LEN + TAG_LEN);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', stateKey(), nonce, {
+    authTagLength: TAG_LEN
+  });
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]);
+}
+
+/** The bytes32 the contract is keyed by: keccak256(key). */
+function keyHash(key) {
+  return ethers.utils.id(key);
+}
+
+const ESR_ABI = [
+  'function commit(bytes32 key, string newCID, uint256 expectedVersion)',
+  'function getState(address enclave, bytes32 key) view returns (string cid, uint256 version, uint64 updatedAt)',
+  'function getVersion(address enclave, bytes32 key) view returns (uint256)',
+  'function exists(address enclave, bytes32 key) view returns (bool)'
+];
+
+class StateRegistry {
+  constructor() {
+    if (!_contractAddress) {
+      throw new Error(
+        'ESR is not enabled for this enclave. Enable it (ECLD_ESR_ENABLE) and ' +
+          'rebuild, so the registry address is baked into the image.'
+      );
+    }
+    this._priv = null;
+  }
+
+  /** The enclave's on-chain address — safe to publish and to fund. */
+  get walletAddress() {
+    return esr_wallet.deriveWalletAddress(_identityPriv);
+  }
+
+  _signer() {
+    // Reuse esr_wallet's derivation rather than repeating it here: two copies
+    // would eventually disagree, and the address a client funds would stop
+    // matching the key that signs. The key stays inside this method.
+    if (this._priv === null) {
+      this._priv = esr_wallet._deriveWalletPrivateKey(_identityPriv);
+    }
+    return new ethers.Wallet(this._priv, _provider);
+  }
+
+  _contract(signerOrProvider) {
+    return new ethers.Contract(_contractAddress, ESR_ABI, signerOrProvider || _provider);
+  }
+
+  /** Current on-chain version for `key`; 0 when never committed. */
+  async getVersion(key) {
+    const v = await this._contract().getVersion(this.walletAddress, keyHash(key));
+    return Number(v);
+  }
+
+  /**
+   * Decrypted state for `key`, or `fallback` ({} by default) when absent.
+   *
+   * Throws on a pointer that is not a CID: treating a broken pointer as "no
+   * state" would let the next commit overwrite data that is still recoverable.
+   */
+  async get(key, fallback = {}) {
+    const [cid, version] = await this._contract().getState(this.walletAddress, keyHash(key));
+    if (!version || !cid) return fallback;
+    if (!looksLikeCID(cid)) {
+      throw new Error(
+        `ESR entry for '${key}' holds a pointer that is not a CID (${cid.slice(0, 32)}…). ` +
+          'The committing code is writing a non-CID value.'
+      );
+    }
+    const blob = await this._fetch(key, cid);
+    return JSON.parse(decrypt(blob).toString('utf8'));
+  }
+
+  /**
+   * Read-modify-write `key` under optimistic concurrency.
+   *
+   * `mutate` receives the current state and returns the new state. If another
+   * commit lands in between, the contract rejects ours and we re-read and
+   * retry, so concurrent tasks cannot silently lose updates.
+   */
+  async commit(key, mutate, attempts = 3) {
+    let lastError = null;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      // eslint-disable-next-line no-await-in-loop
+      const currentVersion = await this.getVersion(key);
+      // eslint-disable-next-line no-await-in-loop
+      const current = currentVersion ? await this.get(key) : {};
+      const newState = await mutate(current);
+
+      const blob = encrypt(Buffer.from(JSON.stringify(newState), 'utf8'));
+      // Compute the CID from OUR bytes — never accept one from the node.
+      const cid = cidv1Raw(blob);
+
+      // Hand the blob and the CID to the node for pinning. It verifies the CID
+      // matches; it does not get to choose it. Fire-and-forget.
+      // eslint-disable-next-line no-await-in-loop
+      await this._publish(key, blob, cid);
+
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await this._sendCommit(keyHash(key), cid, currentVersion);
+        return newState;
+      } catch (e) {
+        const msg = String(e && e.message ? e.message : e);
+        if (/VersionMismatch/i.test(msg) || /version/i.test(msg)) {
+          lastError = e;
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+        throw e;
+      }
+    }
+    throw new Error(`ESR commit failed after ${attempts} attempts: ${lastError}`);
+  }
+
+  async _publish(key, blob, cid) {
+    await _swift.putFileContent(_bucket, `state.${key}.enc`, '', blob);
+    await _swift.putFileContent(_bucket, `state.${key}.cid`, '', cid);
+  }
+
+  /**
+   * Read a state object back, verifying it against the on-chain CID.
+   *
+   * The enclave cannot reach IPFS (the Kubo API binds loopback on the host), so
+   * the node stages state objects in the bucket. That makes the node the
+   * delivery path but not a trusted one: content is checked against the CID the
+   * chain records, so a substituted blob is rejected rather than decrypted.
+   */
+  async _fetch(key, cid) {
+    for (const name of [`state.${key}.enc`, `state.${cid}.enc`]) {
+      // eslint-disable-next-line no-await-in-loop
+      const data = await _swift.getFileContentBytes(_bucket, name).catch(() => null);
+      if (data && data.length) {
+        const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        if (cidv1Raw(buf) !== cid) {
+          throw new Error(
+            `State object ${name} does not match the committed CID ${cid} — refusing to use it`
+          );
+        }
+        return buf;
+      }
+    }
+    throw new Error(`Could not read state object for '${key}' (${cid})`);
+  }
+
+  async _sendCommit(keyHashHex, cid, expectedVersion) {
+    const contract = this._contract(this._signer());
+    const tx = await contract.commit(keyHashHex, cid, expectedVersion);
+    return tx.wait();
+  }
+}
+
+module.exports = {
+  StateRegistry,
+  configure,
+  cidv1Raw,
+  looksLikeCID
+};

package/nodenithy/build/securelock/src/esr_wallet.js

@@ -0,0 +1,147 @@
+// ESR identity wallet derivation (ESR RFC §5.1) — Nodenithy/JS parity with the
+// Python SDK's esr_wallet.py.
+//
+// The enclave's Ethereum wallet is derived from the enclave's IDENTITY PRIVATE
+// KEY (the cert key), never from MR_ENCLAVE:
+//
+//     eth_priv    = keccak256(DOMAIN_SEP || identity_priv_der)  // secp256k1 scalar
+//     eth_address = address(secp256k1(eth_priv))
+//
+// Why derive instead of reusing the cert key: the cert is secp384r1 (P-384) and
+// Ethereum signing requires secp256k1, so a P-384 key can never sign a
+// transaction. Deriving from the identity key means the wallet inherits the
+// identity's security properties automatically:
+//
+//   * mainnet — the identity is PROVISIONED BY CAS as a certificate + private
+//     key over the attested channel. The enclave reads that key from its key
+//     file; it is the same for every node running this MRENCLAVE, so the wallet
+//     is enclave-only and stable.
+//   * testnet — the enclave self-signs, deriving the key from MR_SIGNER/
+//     MR_ENCLAVE (both PUBLIC), so the wallet is public too. Functional testing
+//     only; isSecretIdentity() returns false and callers must warn loudly.
+//
+// BINDING INPUT — the identity private key exactly as the enclave holds it (the
+// certificate's key bytes), matching the Python SDK byte for byte. The cert is
+// the same for a given MR_ENCLAVE on both paths, so its private key is already
+// the stable, canonical input: same MRENCLAVE ⇒ same cert ⇒ same key ⇒ same
+// address. Parsing the key to pull out a raw scalar would add enclave-side
+// parsing surface and a second place for the two languages to disagree, without
+// making a stable value more stable.
+//
+// This does NOT change the enclave's certificate: the P-384 identity keypair and
+// the cert built from it are untouched. ESR only *reads* that key to derive a
+// separate secp256k1 wallet key.
+//
+// DOMAIN_SEP keeps this key from colliding with any other use of the identity
+// key; a second separator derives the state-encryption key in a later phase.
+//
+// SECURITY: nothing here may serialize, log or return the private key. The only
+// value that ever leaves the enclave is the ADDRESS (RFC §5.2) — that is what
+// makes the wallet fundable and readable without weakening secrecy.
+const { ethers } = require('ethers');
+
+const DOMAIN_SEP = 'ethernity-cloud/esr-wallet/v1';
+
+// secp256k1 group order; a valid private scalar is in [1, N-1].
+const SECP256K1_N = BigInt(
+  '0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141'
+);
+
+// keccak256 of DOMAIN_SEP (raw bytes) concatenated with `dataBuf`.
+function keccak(dataBuf) {
+  const sep = Buffer.from(DOMAIN_SEP, 'utf8');
+  return ethers.utils.keccak256(Buffer.concat([sep, dataBuf]));
+}
+
+// The identity key as bytes, exactly as held (PEM text or DER buffer). No
+// re-encoding: whatever the enclave read is what gets hashed, mirroring Python
+// which hashes the private_bytes() PEM/DER it already has.
+function identityKeyBytes(identityPrivDer) {
+  if (Buffer.isBuffer(identityPrivDer)) {
+    if (identityPrivDer.length === 0) {
+      throw new Error('empty enclave identity key; cannot derive ESR wallet');
+    }
+    return identityPrivDer;
+  }
+  const s = String(identityPrivDer || '');
+  if (!s) throw new Error('empty enclave identity key; cannot derive ESR wallet');
+  return Buffer.from(s, 'utf8');
+}
+
+/**
+ * 32-byte secp256k1 private key derived from the enclave identity key.
+ * Kept private to this module's callers; never log or transmit the result.
+ * @param {Buffer|string} identityPrivDer the enclave identity private key (PEM/DER)
+ * @returns {string} 0x-prefixed 32-byte private key hex
+ */
+function deriveWalletPrivateKey(identityPrivDer) {
+  let digest = keccak(identityKeyBytes(identityPrivDer)); // 0x + 64 hex
+  // Astronomically unlikely, but a scalar of 0 or >= N is invalid: re-hash
+  // until valid so derivation is total rather than probabilistically broken.
+  for (;;) {
+    const scalar = BigInt(digest);
+    if (scalar > 0n && scalar < SECP256K1_N) return digest;
+    digest = keccak(Buffer.from(digest.slice(2), 'hex'));
+  }
+}
+
+/**
+ * Checksummed 0x address of the enclave's ESR wallet (safe to publish).
+ * @param {Buffer|string} identityPrivDer the enclave identity private key (PEM/DER)
+ * @returns {string} EIP-55 checksummed address
+ */
+function deriveWalletAddress(identityPrivDer) {
+  const priv = deriveWalletPrivateKey(identityPrivDer);
+  return new ethers.Wallet(priv).address;
+}
+
+/**
+ * True only when the identity key is genuinely unpredictable to outsiders.
+ *
+ * This is NOT "is the enclave genuine" — SGX protects enclave memory on every
+ * network. It is the narrower question the ESR wallet depends on: could someone
+ * outside the enclave reproduce the private key? The distinction is
+ * ATTESTATION, not SGX:
+ *   * mainnet — CAS attests the enclave before provisioning the identity, so the
+ *     key is effectively enclave-only. Intended posture.
+ *   * testnet — NO attestation; the derivation input (MR_ENCLAVE) is public, so
+ *     anyone who rebuilds the image can reproduce the keypair. Deliberate
+ *     testnet tradeoff — treat these wallets as disposable.
+ *
+ * @param {string} networkType "mainnet" | "testnet"
+ * @returns {boolean}
+ */
+function isSecretIdentity(networkType) {
+  const override = String(process.env.ESR_IDENTITY_SECRET || '').trim().toLowerCase();
+  if (override === '1' || override === 'true' || override === 'yes') return true;
+  if (override === '0' || override === 'false' || override === 'no') return false;
+  // Secrecy tracks attestation, not the network name: mainnet is attested,
+  // testnet is not. The override exists for a future attested-testnet build.
+  return String(networkType || '').trim().toLowerCase() === 'mainnet';
+}
+
+const INSECURE_IDENTITY_WARNING =
+  '[TESTNET-INSECURE] This network runs the enclave on SGX but WITHOUT ' +
+  "attestation, so the ESR wallet's keypair — though generated inside the " +
+  'enclave — is reproducible by anyone who rebuilds the image (its derivation ' +
+  'input, MR_ENCLAVE, is public and nothing verifies the enclave). This is a ' +
+  'deliberate testnet tradeoff, not a defect. Treat the wallet as disposable ' +
+  'and do not fund it with real value. (An attested testnet build can set ' +
+  'ESR_IDENTITY_SECRET=1 to suppress this warning.)';
+
+// deriveWalletPrivateKey is deliberately NOT exported. The client payload is
+// eval'd inside etny_exec's module scope, where require() is reachable, so an
+// exported key-derivation helper would hand untrusted code a ready-made way to
+// materialize the ESR private key. Only the ADDRESS leaves this module (RFC
+// §5.2); the wallet key stays an implementation detail of deriveWalletAddress.
+module.exports = {
+  DOMAIN_SEP,
+  deriveWalletAddress,
+  isSecretIdentity,
+  INSECURE_IDENTITY_WARNING,
+  // Underscored to mark it private: it is exported ONLY so ecld_state can build
+  // the signing wallet, since duplicating the derivation there would risk the
+  // two copies drifting apart. Payload code must never call this -- the address
+  // is the public surface, the key is not.
+  _deriveWalletPrivateKey: deriveWalletPrivateKey,
+};