@ethernity-cloud/sdk-js 1.4.0 → 1.5.1

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

@@ -24,6 +24,7 @@ const contract_abi = require('./pox_abi');
 const image_registry_abi = require('./image_registry_abi');
 const {sha256} = require("./etny_crypto");
 const {generateCertFromMrEnclave} = require("./self_sign");
+const esr_wallet = require("./esr_wallet");
 
 // Baked per network by CI (render_network.sh): "mainnet" | "testnet". On testnet
 // the enclave self-signs its cert from MR_ENCLAVE (non-CAS mode); on mainnet the
@@ -43,6 +44,10 @@ class EtnySecureLock {
 
     setInitializers() {
         this.is_valid_client_data = true;
+        // Testnet holds the self-derived identity key HERE, in memory only, and
+        // never writes it. Stays null on mainnet, where CAS injects the key into
+        // key_file and every consumer reads that path exactly as before.
+        this.identity_private_key_pem = null;
         this.key_file = "/private/__ENCLAVE_NAME_SECURELOCK__/key.pem";
         this.cert_file = "/app/__ENCLAVE_NAME_SECURELOCK__/cert.pem";
         this.pub_cert_file = "/app/__ENCLAVE_NAME_SECURELOCK__/enclave_pub_cert.pem";
@@ -230,7 +235,7 @@ class EtnySecureLock {
             const encryptedBase64 = await this.swiftStreamService.getFileContent(bucketName, objectName);
 
             const encryptedTuple = etny_crypto.encryptedDataFromBase64Json(encryptedBase64);
-            const decryptedResult = etny_crypto.decrypt(this.key_file, encryptedTuple);
+            const decryptedResult = etny_crypto.decrypt(this.privateKeyMaterial(), encryptedTuple);
             return decryptedResult.toString();
         } catch (e) {
             console.log(`Failed to get ${objectName} file`);
@@ -282,37 +287,68 @@ class EtnySecureLock {
     }
 
     resetPrivateCertFile() {
-        //console.log('Resetting the cert file');
+        // Wipes the CAS-injected key from disk after it has been loaded
+        // (mainnet PRODUCTION hygiene). On testnet the key was never written --
+        // it lives only in memory -- so there is nothing on disk to wipe and the
+        // truncate/read below would throw on a file that does not exist.
+        //
+        // The in-memory key is deliberately NOT cleared here: waitForPayloadAndInput
+        // still needs it later to decrypt the payload/input, which runs after
+        // create() has called this. Clearing it would break the task on testnet only.
+        if (this.identity_private_key_pem) {
+            return;
+        }
         try {
-            // const fd = fs.openSync(this.private_key_file, 'w+');
             fs.truncate(this.key_file, 0, function () {
                 //console.log('Private certificate file was cleaned.')
             });
-            // fs.closeSync(fd);
         } catch (e) {
             //console.log('Error while removing the private key file content', e);
         }
-        const content = fs.readFileSync(this.key_file, 'utf8');
-        //console.log('cert file content', content, '##################');
+        try {
+            fs.readFileSync(this.key_file, 'utf8');
+        } catch (e) {
+            // Nothing to read back; the wipe above is what mattered.
+        }
     }
 
     // Testnet non-CAS mode: derive a deterministic self-signed cert/key from this
-    // enclave's MR_ENCLAVE and write them to the paths the rest of the code reads
-    // (key_file for decrypt, cert_file for savePublicCert). No-op on mainnet,
-    // where CAS injects the cert/key into those same paths. Idempotent: the key
-    // is a pure function of MR_ENCLAVE so it is identical across restarts.
+    // enclave's identity. The CERTIFICATE is written (it is public, and
+    // savePublicCert reads it back to publish it); the PRIVATE KEY is kept ONLY
+    // in memory and never touches the filesystem.
+    //
+    // Why memory-only: on testnet there is no CAS and no attestation, so nothing
+    // provisions or protects the key from outside the enclave. Not writing it at
+    // all removes every at-rest attack on it outright, instead of relying on the
+    // file protection being keyed by something trustworthy on this path.
+    //
+    // MAINNET IS UNCHANGED: this method returns immediately there, CAS still
+    // injects cert+key into key_file/cert_file, and every consumer still reads
+    // key_file exactly as before (this.identity_private_key_pem stays null, and
+    // privateKeyMaterial() falls back to the path).
+    //
+    // Idempotent: the key is a pure function of the enclave identity, so it is
+    // identical across restarts without needing to persist it.
     generateSelfSignedCertIfTestnet() {
         if (NETWORK_TYPE !== "testnet") return;
         console.log("[SecureLock] TESTNET: self-signing certificate from MR_ENCLAVE (no CAS) [TESTNET-INSECURE]");
         const {privateKeyPem, certPem, mrEnclaveHex} = generateCertFromMrEnclave("SecureLock Enclave");
         console.log(`[SecureLock] MR_ENCLAVE: ${mrEnclaveHex}`);
-        for (const f of [this.key_file, this.cert_file, this.pub_cert_file]) {
+        for (const f of [this.cert_file, this.pub_cert_file]) {
             try { fs.mkdirSync(require('path').dirname(f), {recursive: true}); } catch (e) {}
         }
-        fs.writeFileSync(this.key_file, privateKeyPem);
+        // Private key: memory only. Deliberately NOT written to this.key_file.
+        this.identity_private_key_pem = privateKeyPem;
         fs.writeFileSync(this.cert_file, certPem);
     }
 
+    // The enclave's identity private key, in whatever form this network provides
+    // it: the in-memory PEM on testnet, or the CAS-injected key_file path on
+    // mainnet. etny_crypto accepts either, so callers do not branch on network.
+    privateKeyMaterial() {
+        return this.identity_private_key_pem || this.key_file;
+    }
+
     async savePublicCert() {
         try {
             const content = await fs.promises.readFile(this.cert_file, 'utf8');
@@ -321,12 +357,46 @@ class EtnySecureLock {
             console.log(`PUBLIC_KEY:`);
             console.log(content);
 
+            // ESR (RFC §5.2): emit the enclave's ESR wallet ADDRESS on the same
+            // harvest channel as the cert, so publish (or the remote extraction
+            // service) can capture it. It MUST be derived here rather than by the
+            // service: on mainnet the identity key is CAS-provisioned and exists
+            // only inside this enclave, so nobody outside can compute the address.
+            // Only the address is emitted — the private key never leaves.
+            this.emitEsrWalletAddress();
+
             await this.swiftStreamService.putFileContent(this.etny_bucket, 'cert.pem', this.pub_cert_file);
         } catch (err) {
             console.error(err);
         }
     }
 
+    // ESR wallet address emission (RFC §5.2). Gated on ESR_CONTRACT_ADDRESS being
+    // set, exactly like the Python securelock, so non-ESR images print nothing.
+    // Derived from the enclave's own identity private key (the certificate key);
+    // only the ADDRESS is logged, never the key. Any failure is reported as
+    // ESR_WALLET_ERROR and never breaks cert harvest or a task.
+    emitEsrWalletAddress() {
+        if (!String(process.env.ESR_CONTRACT_ADDRESS || "").trim()) return;
+        try {
+            // The identity key the enclave actually holds: the CAS-provisioned
+            // key_file on mainnet (nothing in-enclave can re-derive it), or the
+            // in-memory PEM on testnet (never written to disk). Hashed as-is,
+            // matching the Python SDK.
+            const identityPriv = this.identity_private_key_pem
+                || fs.readFileSync(this.key_file, 'utf8');
+            const esrAddress = esr_wallet.deriveWalletAddress(identityPriv);
+            console.log(`ESR_WALLET_ADDRESS: ${esrAddress}`);
+            if (!esr_wallet.isSecretIdentity(NETWORK_TYPE)) {
+                console.warn(esr_wallet.INSECURE_IDENTITY_WARNING);
+            }
+        } catch (e) {
+            // Never let ESR derivation break harvest/a task: report it the way
+            // every other enclave-side config problem is reported.
+            console.error(`ESR_WALLET_ERROR: ${e && e.message ? e.message : e}`);
+        }
+    }
+
     async saveResult() {
         try {
             await this.getTrustedZonePublicKey();
@@ -342,6 +412,37 @@ class EtnySecureLock {
         }
     }
 
+    // Make StateRegistry usable from payload code, if ESR is enabled.
+    //
+    // Wires ecld_state to this enclave's identity key, the SwiftStream client
+    // and bucket the node shares with us, the registry address baked in at build
+    // time, and the provider. Payload code then just does:
+    //
+    //     const {StateRegistry} = require('./ecld_state');
+    //     await new StateRegistry().commit('key', s => ...);
+    //
+    // No-op when ESR is disabled, so non-ESR enclaves are unaffected. Never
+    // throws: a setup problem must not stop the task from running -- payload
+    // code that then uses StateRegistry gets a clear error from the registry
+    // itself rather than a task that died before starting.
+    configureStateRegistry() {
+        const contractAddress = String(process.env.ESR_CONTRACT_ADDRESS || "").trim();
+        if (!contractAddress) return;
+        try {
+            const ecld_state = require("./ecld_state");
+            ecld_state.configure({
+                identityPriv: this.identity_private_key_pem || fs.readFileSync(this.key_file, 'utf8'),
+                swiftStreamService: this.swiftStreamService,
+                bucket: this.etny_bucket,
+                contractAddress: contractAddress,
+                provider: this.w3,
+            });
+            console.log(`StateRegistry ready (ESR ${contractAddress})`);
+        } catch (e) {
+            console.error(`ESR_STATE_ERROR: could not configure StateRegistry: ${e && e.message ? e.message : e}`);
+        }
+    }
+
     async execute() {
         const payload_data = await this.getFileContentAndDecrypt(this.etny_bucket, this.payload);
         const input_data = await this.getFileContentAndDecrypt(this.etny_bucket, this.input);
@@ -355,6 +456,8 @@ class EtnySecureLock {
             return false;
         }
 
+        this.configureStateRegistry();
+
         const task_result = executeTask(payload_data, input_data);
         console.log('TASK RESULT (code, data):', task_result);
         this.task_code = task_result[0];
@@ -378,6 +481,40 @@ function initSwiftStreamClient() {
     return swiftStreamClient;
 }
 
+// Set as soon as the enclave object exists so the top-level catch can report a
+// failure result even when the throw happens deep inside execute().
+let currentApp = null;
+
+/**
+ * Best-effort: write a failure result so the trustedzone stops waiting.
+ *
+ * Securelock only publishes the result and its code; the trustedzone reads
+ * those and builds the signed transaction. Without them that wait runs to its
+ * timeout and the whole order stalls with no diagnosis.
+ *
+ * Guarded throughout: this runs while already handling a failure, so it must
+ * never throw or hang.
+ */
+async function reportFailure(app, err) {
+    if (!app) {
+        console.log('cannot report failure: enclave died before initialization');
+        return;
+    }
+    try {
+        // Keep a specific code if one was already set (checksum mismatch, ...).
+        if (app.task_code === undefined || app.task_code === null || app.task_code === '') {
+            app.task_code = TaskStatus.SYSTEM_ERROR;
+        }
+        if (!app.task_result) {
+            app.task_result = `ENCLAVE ERROR: ${err && err.message ? err.message : err}`;
+        }
+        await app.saveResult();
+        console.log(`failure reported (task_code=${app.task_code})`);
+    } catch (reportErr) {
+        console.log('could not report the failure result:', reportErr);
+    }
+}
+
 async function execute() {
     console.log('########################################');
     console.log('########################################');
@@ -391,6 +528,9 @@ async function execute() {
     const swiftStreamClient = initSwiftStreamClient();
 
     const app = new EtnySecureLock(swiftStreamClient);
+    // Exposed so the top-level handler can still publish a failure result if
+    // anything below throws (see reportFailure).
+    currentApp = app;
 
     // Testnet: materialize the self-signed cert/key from MR_ENCLAVE into the
     // file paths before anything reads them (harvest + decrypt). No-op on mainnet
@@ -440,5 +580,7 @@ async function execute() {
         await execute();
     } catch (e) {
         console.log(e);
+        await reportFailure(currentApp, e);
+        process.exitCode = 1;
     }
 })();

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

@@ -11,6 +11,10 @@ class TaskStatus {
     // Extended diagnostic (matches the trustedzone's extended enum): the
     // serverless backend failed to load, so none of its functions exist.
     static IMPORT_ERROR = 28;
+    // A required enclave config value is present but EMPTY (e.g. an ESR
+    // address that was never baked into the sealed image). Reported eagerly
+    // with the variable named, instead of a confusing downstream crash.
+    static CONFIG_ERROR = 32;
 }
 
 module.exports = {

package/nodenithy/build.mjs

@@ -156,9 +156,27 @@ if (!fs.existsSync('src/sgx_report.node')) {
   console.error('       securelock/src/ (see src/README-keygen.md) before building.');
   process.exit(1);
 }
+// ESR fail-fast gate (RFC §5.4), mirroring the Python SDK's validate_esr_config:
+// never build an ESR-enabled enclave with an unresolved registry address. The
+// enclave is SEALED -- a missing value bakes in as empty, and every task then
+// fails at runtime after gas is already spent. ESR is opt-in: absent/false
+// ESR_ENABLED means the build behaves exactly as it did before ESR existed.
+const ESR_ENABLED = /^(1|true|yes)$/i.test(String(process.env.ESR_ENABLED || '').trim());
+const ESR_CONTRACT_ADDRESS = String(process.env.ESR_CONTRACT_ADDRESS || '').trim();
+if (ESR_ENABLED && !/^0x[0-9a-fA-F]{40}$/.test(ESR_CONTRACT_ADDRESS)) {
+  console.error('ERROR: ESR is enabled but ESR_CONTRACT_ADDRESS is not a valid address'
+    + ` (got ${JSON.stringify(ESR_CONTRACT_ADDRESS)}).`);
+  console.error('       The enclave is sealed: a missing value bakes in as EMPTY and every');
+  console.error('       task fails at runtime after gas is spent. Set it with:');
+  console.error('         ecld-init (ESR step) or ESR_CONTRACT_ADDRESS in .env');
+  process.exit(1);
+}
+// Rendered only when enabled, so non-ESR images keep byte-identical layers.
+const esrEnvBlock = ESR_ENABLED ? `ENV ESR_CONTRACT_ADDRESS=${ESR_CONTRACT_ADDRESS}` : '';
+
 // runCommand(`cat Dockerfile.tmpl | sed s/"__ENCLAVE_NAME_SECURELOCK__"/"${ENCLAVE_NAME_SECURELOCK}"/g > Dockerfile`);
 const dockerfileSecureTemplate = fs.readFileSync('Dockerfile.tmpl', 'utf8');
-let dockerfileSecureContent = dockerfileSecureTemplate.replace(/__ENCLAVE_NAME_SECURELOCK__/g, ENCLAVE_NAME_SECURELOCK).replace(/__BUCKET_NAME__/g, templateName + "-v3").replace(/__SMART_CONTRACT_ADDRESS__/g, ECRunner[templateName][0]).replace(/__IMAGE_REGISTRY_ADDRESS__/g, ECRunner[templateName][1]).replace(/__RPC_URL__/g, ECRunner[templateName][2]).replace(/__CHAIN_ID__/g, ECRunner[templateName][3]).replace(/__TRUSTED_ZONE_IMAGE__/g, templateName);
+let dockerfileSecureContent = dockerfileSecureTemplate.replace(/__ENCLAVE_NAME_SECURELOCK__/g, ENCLAVE_NAME_SECURELOCK).replace(/__BUCKET_NAME__/g, templateName + "-v3").replace(/__SMART_CONTRACT_ADDRESS__/g, ECRunner[templateName][0]).replace(/__IMAGE_REGISTRY_ADDRESS__/g, ECRunner[templateName][1]).replace(/__RPC_URL__/g, ECRunner[templateName][2]).replace(/__CHAIN_ID__/g, ECRunner[templateName][3]).replace(/__TRUSTED_ZONE_IMAGE__/g, templateName).replace(/^__ESR_ENV__\n/m, esrEnvBlock ? `${esrEnvBlock}\n` : '');
 
 // Amount of enclave heap to allocate (SCONE_HEAP). Kept in sync with the
 // run/docker-compose securelock service; overridable via ECLD_MEMORY_TO_ALLOCATE.

package/nodenithy/run/public_key_service.js

@@ -78,6 +78,17 @@ console.log("Docker Composer Hash:", dockerComposerHash);
                 console.log("Public Key:", checkResponse.publicKey);
                 // Save public key to file
                 fs.writeFileSync('PUBLIC_KEY.txt', checkResponse.publicKey);
+                // ESR (RFC §5.2): the enclave also prints ESR_WALLET_ADDRESS on the
+                // cert channel. The service currently returns only "publicKey"; when
+                // it starts relaying the enclave's output (or adds an
+                // "esrWalletAddress" field) it is picked up here and written to a
+                // sibling file the caller reads -- no other changes needed. Until
+                // then, ESR projects extract locally on an SGX host once to learn
+                // the address (publish then persists it).
+                if (checkResponse.esrWalletAddress) {
+                    console.log("ESR Wallet Address:", checkResponse.esrWalletAddress);
+                    fs.writeFileSync('ESR_WALLET_ADDRESS.txt', checkResponse.esrWalletAddress);
+                }
                 break;
             }
         } else {

package/nodenithy/run.js

@@ -497,6 +497,28 @@ const main = async () => {
                 console.error("Error: Could not fetch PUBLIC_KEY_SECURELOCK");
                 process.exit(1);
             }
+            // ESR (RFC §5.2): if the extraction relayed the enclave's ESR wallet
+            // address (public_key_service writes ESR_WALLET_ADDRESS.txt when the
+            // service provides it), persist it to .env so a dApp can read/fund the
+            // enclave wallet. Absent file => not an ESR project, or the (mainnet)
+            // address must be learned from a local SGX extraction — either way,
+            // silently skip. Parity with the Python SDK's esr.wallet_address.
+            try {
+                if (fs.existsSync('ESR_WALLET_ADDRESS.txt')) {
+                    const esrAddr = fs.readFileSync('ESR_WALLET_ADDRESS.txt', 'utf8').trim();
+                    if (/^0x[0-9a-fA-F]{40}$/.test(esrAddr)) {
+                        writeEnv('ESR_WALLET_ADDRESS', esrAddr);
+                        console.log(`ESR_WALLET_ADDRESS: ${esrAddr}`);
+                        // Manual funding by the data owner is the default path;
+                        // publishing never transfers value on its own. Say so, or
+                        // the first task needing gas fails with no clue why.
+                        console.log('   This wallet starts EMPTY. Fund it from your own wallet with');
+                        console.log('   whatever your payload needs; publishing never transfers value.');
+                    }
+                }
+            } catch (e) {
+                console.warn(`Could not persist ESR_WALLET_ADDRESS: ${e && e.message ? e.message : e}`);
+            }
         };
     }
 

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@ethernity-cloud/sdk-js",
-  "version": "1.4.0",
-  "description": "A package to run ethernity cloud build scripts",
-  "scripts": {
-    "ecld-build": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/build.js",
-    "ecld-publish": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/publish.js",
-    "ecld-init": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/init.js",
-    "ecld-run": "cross-env ecld-run",
-    "postinstall": "node postinstall.js",
-    "ecld-test": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/test.js"
-  },
-  "bin": {
-    "ecld-build": "./build.js",
-    "ecld-publish": "./publish.js",
-    "ecld-init": "./init.js",
-    "postinstall": "./postinstall.js",
-    "ecld-test": "./test.js"
-  },
-  "files": [
-    "nodenithy/*",
-    "pynithy/*",
-    "build.js",
-    "init.js",
-    "publish.js",
-    "postinstall.js"
-  ],
-  "dependencies": {
-    "@ethernity-cloud/runner": "^0.0.26",
-    "axios": "^1.7.2",
-    "commander": "^12.1.0",
-    "dotenv": "^16.4.5",
-    "eth-lib": "^0.1.29",
-    "ethers": "^5.5.4",
-    "kubo-rpc-client": "^4.1.1",
-    "web3": "^4.9.0",
-    "cross-env": "^7.0.3",
-    "shelljs": "^0.8.5",
-    "shx": "^0.3.4",
-    "node-forge": "^1.3.1",
-    "cli-progress": "^3.12.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-scripts": "^5.0.1",
-    "web-vitals": "^2.1.4",
-    "adm-zip": "^0.5.14"
-  },
-  "author": "Alexandru Luca",
-  "license": "AGPL-3.0"
-}
+{
+  "name": "@ethernity-cloud/sdk-js",
+  "version": "1.5.1",
+  "description": "A package to run ethernity cloud build scripts",
+  "scripts": {
+    "ecld-build": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/build.js",
+    "ecld-publish": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/publish.js",
+    "ecld-init": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/init.js",
+    "ecld-run": "cross-env ecld-run",
+    "postinstall": "node postinstall.js",
+    "ecld-test": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/test.js"
+  },
+  "bin": {
+    "ecld-build": "./build.js",
+    "ecld-publish": "./publish.js",
+    "ecld-init": "./init.js",
+    "postinstall": "./postinstall.js",
+    "ecld-test": "./test.js"
+  },
+  "files": [
+    "nodenithy/*",
+    "pynithy/*",
+    "build.js",
+    "init.js",
+    "publish.js",
+    "postinstall.js"
+  ],
+  "dependencies": {
+    "@ethernity-cloud/runner": "^0.0.26",
+    "axios": "^1.7.2",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "eth-lib": "^0.1.29",
+    "ethers": "^5.5.4",
+    "kubo-rpc-client": "^4.1.1",
+    "web3": "^4.9.0",
+    "cross-env": "^7.0.3",
+    "shelljs": "^0.8.5",
+    "shx": "^0.3.4",
+    "node-forge": "^1.3.1",
+    "cli-progress": "^3.12.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-scripts": "^5.0.1",
+    "web-vitals": "^2.1.4",
+    "adm-zip": "^0.5.14"
+  },
+  "author": "Alexandru Luca",
+  "license": "AGPL-3.0"
+}