@ethernity-cloud/sdk-js 1.2.0 → 1.5.0

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

@@ -0,0 +1,76 @@
+// Testnet non-CAS self-sign: derive a DETERMINISTIC secp384r1 key + self-signed
+// X509 from the enclave's own MR_ENCLAVE / MR_SIGNER (read via the sgx_report
+// N-API addon). Only the exact attested enclave can regenerate this key, so the
+// harvested cert (registered on-chain) survives restarts and stays consistent.
+// [TESTNET-INSECURE] -- testnet runs pre-release SGX; NOT a production guarantee.
+//
+// Cert-compatibility note: nodenithy's trustedzone fetches the securelock public
+// key from the on-chain image registry (getImageCertPublicKey) and does NOT
+// re-derive it from MR_ENCLAVE. Both enclaves are Node. So this cert only needs
+// to be a valid P-384 X509 that is STABLE per MR_ENCLAVE and readable by
+// etny_crypto (jsrsasign KEYUTIL for the key, crypto.createPublicKey/ec-key for
+// the cert). It does NOT need to be byte-identical to pynithy's Python DER.
+const rs = require('jsrsasign');
+const sgx = require('./sgx_report');
+
+// The identity-key derivation lives ENTIRELY in the compiled addon
+// (get_sgx_report.c, via sgx_report.deriveIdentityScalar). It is not present in
+// this interpreted source, so reading self_sign.js reveals nothing about how
+// the key is derived. Each enclave uses its own role tag inside the addon, so
+// the derivations are mutually decoupled. role: 0=securelock 1=trustedzone
+// 2=validator, selected from the subject CN.
+function roleForSubject(subjectCN) {
+  const cn = String(subjectCN || '').toLowerCase();
+  if (cn.includes('securelock')) return 0;
+  if (cn.includes('validator')) return 2;
+  return 1;
+}
+
+/**
+ * Generate the deterministic self-signed cert for this enclave.
+ * @param {string} subjectCN e.g. "SecureLock Enclave" / "TrustedZone Enclave [TESTNET-INSECURE]"
+ * @returns {{privateKeyPem: string, certPem: string, mrEnclaveHex: string}}
+ */
+function generateCertFromMrEnclave(subjectCN) {
+  const mrEnclaveHex = sgx.getMrEnclave();  // 64 hex chars (32 bytes)
+
+  // Derivation performed inside the compiled addon; role from the subject CN.
+  const privHex = sgx.deriveIdentityScalar(roleForSubject(subjectCN));
+
+  // Build the EC keypair from the deterministic private scalar (jsrsasign).
+  const ecKeypair = rs.KEYUTIL.generateKeypair('EC', 'secp384r1');
+  const prvKey = new rs.KJUR.crypto.ECDSA({ curve: 'secp384r1' });
+  prvKey.setPrivateKeyHex(privHex);
+  prvKey.generatePublicKeyHex();  // derive pub from priv
+  void ecKeypair;
+
+  const pubKey = new rs.KJUR.crypto.ECDSA({ curve: 'secp384r1' });
+  pubKey.setPublicKeyHex(prvKey.pubKeyHex);
+
+  // Self-signed X509: fixed serial/validity so the cert is stable per key. No
+  // custom MR_ENCLAVE extension -- unlike pynithy (whose cert carries it as an
+  // informational OID), nothing in nodenithy reads it: the trustedzone uses the
+  // securelock public key fetched from the on-chain image registry, not the cert
+  // extensions. Keeping the cert minimal avoids jsrsasign generic-extension API
+  // fragility across versions. mrEnclaveHex is still returned for logging.
+  const cert = new rs.KJUR.asn1.x509.Certificate({
+    version: 3,
+    serial: { int: 31337 },
+    issuer: { str: '/CN=' + subjectCN },
+    subject: { str: '/CN=' + subjectCN },
+    notbefore: '250101000000Z',
+    notafter: '350101000000Z',
+    sbjpubkey: pubKey,
+    sigalg: 'SHA256withECDSA',
+    cakey: prvKey,
+  });
+
+  const certPem = cert.getPEM();
+
+  // Private key as PKCS8 PEM (etny_crypto reads it via rs.KEYUTIL.getKey().prvKeyHex).
+  const privateKeyPem = rs.KEYUTIL.getPEM(prvKey, 'PKCS8PRV');
+
+  return { privateKeyPem, certPem, mrEnclaveHex };
+}
+
+module.exports = { generateCertFromMrEnclave };

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

@@ -0,0 +1,50 @@
+// Loader for the SGX EREPORT N-API addon (sgx_report.node), which exposes the
+// enclave's own MR_ENCLAVE / MR_SIGNER (used to deterministically derive the
+// testnet self-signed cert). The addon is compiled from sgx_report_napi.c +
+// get_sgx_report.c at build time and baked into binary-fs (see the Dockerfile).
+const path = require('path');
+
+let addon = null;
+function load() {
+  if (addon) return addon;
+  // The addon sits next to the enclave sources in the image; try a couple of
+  // resolutions so it works in the enclave (/etny-securelock) and in local test.
+  const candidates = [
+    path.join(__dirname, 'sgx_report.node'),
+    '/etny-trustedzone/sgx_report.node',
+    './sgx_report.node',
+  ];
+  let lastErr;
+  for (const p of candidates) {
+    try {
+      addon = require(p);
+      return addon;
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw new Error('Failed to load sgx_report.node addon: ' + (lastErr && lastErr.message));
+}
+
+function getMrEnclave() {
+  const v = load().getMrEnclave();
+  if (!v) throw new Error('get_mr_enclave() returned null (EREPORT failed)');
+  return v;
+}
+
+function getMrSigner() {
+  const v = load().getMrSigner();
+  if (!v) throw new Error('get_mr_signer() returned null (EREPORT failed)');
+  return v;
+}
+
+// Consolidated identity-key derivation, performed inside the compiled addon
+// (get_sgx_report.c). role: 0=securelock, 1=trustedzone, 2=validator.
+// Returns the 96-hex secp384r1 scalar. The algorithm is NOT in self_sign.js.
+function deriveIdentityScalar(role) {
+  const v = load().deriveIdentityScalar(role | 0);
+  if (!v) throw new Error('deriveIdentityScalar() returned null');
+  return v;
+}
+
+module.exports = { getMrEnclave, getMrSigner, deriveIdentityScalar };

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

@@ -8,6 +8,13 @@ class TaskStatus {
     static PAYLOAD_CHECKSUM_ERROR = 6;
     static INPUT_CHECKSUM_ERROR = 7;
     static EVAL_ERROR = 8;
+    // 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.js

@@ -67,6 +67,28 @@ runCommand(`docker rm registry -f`);
 
 const srcDir = './src/serverless';
 const destDir = path.join(buildDir, 'securelock/src/serverless');
+
+// Fail the build NOW if the backend is missing or unparseable. An enclave
+// built without a valid backend runs every task into "X is not defined" /
+// IMPORT_ERROR on-chain — expensive to discover after building, publishing
+// and paying for a task.
+const backendFile = path.join(srcDir, 'backend.js');
+if (!fs.existsSync(backendFile)) {
+  console.error(`ERROR: ${backendFile} not found.`);
+  console.error('       The securelock enclave loads your functions from src/serverless/backend.js;');
+  console.error('       without it no backend function will exist inside the enclave.');
+  console.error('       Run ecld-init to scaffold it, or create the file before building.');
+  process.exit(1);
+}
+try {
+  require(path.resolve(backendFile));
+} catch (e) {
+  console.error('ERROR: src/serverless/backend.js failed to load and would fail inside the enclave:');
+  console.error(`       ${e.name || 'Error'}: ${e.message}`);
+  console.error('       Fix the module (missing dependency? bad require?) before building.');
+  process.exit(1);
+}
+
 console.log(`Creating destination directory: ${destDir}`);
 fs.mkdirSync(destDir, { recursive: true });
 

package/nodenithy/build.mjs

@@ -92,6 +92,29 @@ runCommand(`docker rm registry -f`);
 
 const srcDir = './src/serverless';
 const destDir = path.join(buildDir, 'securelock/src/serverless');
+
+// Fail the build NOW if the backend is missing or unloadable. An enclave
+// built without a valid backend runs every task into "X is not defined" /
+// IMPORT_ERROR on-chain — expensive to discover after building, publishing
+// and paying for a task.
+const backendFile = path.join(srcDir, 'backend.js');
+if (!fs.existsSync(backendFile)) {
+  console.error(`ERROR: ${backendFile} not found.`);
+  console.error('       The securelock enclave loads your functions from src/serverless/backend.js;');
+  console.error('       without it no backend function will exist inside the enclave.');
+  console.error('       Run ecld-init to scaffold it, or create the file before building.');
+  process.exit(1);
+}
+try {
+  const { createRequire } = await import('module');
+  createRequire(import.meta.url)(path.resolve(backendFile));
+} catch (e) {
+  console.error('ERROR: src/serverless/backend.js failed to load and would fail inside the enclave:');
+  console.error(`       ${e.name || 'Error'}: ${e.message}`);
+  console.error('       Fix the module (missing dependency? bad require?) before building.');
+  process.exit(1);
+}
+
 console.log(`Creating destination directory: ${destDir}`);
 fs.mkdirSync(destDir, { recursive: true });
 
@@ -120,9 +143,40 @@ writeEnv('ENCLAVE_NAME_SECURELOCK', ENCLAVE_NAME_SECURELOCK);
 
 console.log('Building etny-securelock');
 process.chdir('securelock');
+
+// The SGX key-gen module ships as a PREBUILT sgx_report.node (never the .c
+// source). It is a build artifact of the etny-nodenithy pipeline; the
+// securelock Dockerfile bakes it into binary-fs but does not compile it. Fail
+// fast with a clear message if it is missing, rather than producing an enclave
+// that crashes on the missing addon at runtime.
+if (!fs.existsSync('src/sgx_report.node')) {
+  console.error('ERROR: securelock/src/sgx_report.node not found.');
+  console.error('       The SDK ships the SGX key-gen module as a prebuilt .node, not source.');
+  console.error('       It is a build artifact of the etny-nodenithy pipeline; copy it into');
+  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,19 +1,21 @@
 {
   "name": "@ethernity-cloud/sdk-js",
-  "version": "1.2.0",
+  "version": "1.5.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"
+    "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"
+    "postinstall": "./postinstall.js",
+    "ecld-test": "./test.js"
   },
   "files": [
     "nodenithy/*",
@@ -45,4 +47,4 @@
   },
   "author": "Alexandru Luca",
   "license": "AGPL-3.0"
-}
+}

package/test.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/* ecld-test — run a Nodenithy payload locally, without SGX, exactly as the
+ * enclave would.
+ *
+ * Stages the project's src/serverless next to the vendored securelock
+ * executor (the same layout ecld-build produces inside the enclave image) and
+ * executes the payload with that executor: same backend reflection, same
+ * ___etny_result___ / ___etny_data_set___ scope, same TaskStatus codes.
+ * Validates the CALL — names, arguments, result wiring — before anything is
+ * paid for on-chain. It does not validate attestation, checksums or
+ * encryption; those need a real (testnet) run.
+ *
+ * Usage, from the project root:
+ *
+ *   npx ecld-test 'hello("World")'              one-shot, in-process
+ *   npx ecld-test --file payload.js
+ *   npx ecld-test --input data.json 'processData(___etny_data_set___)'
+ *   npx ecld-test --input-text '{"x":1}' 'processData(___etny_data_set___)'
+ *
+ *   npx ecld-test serve [--port 8745]           local API for runner LOCAL mode
+ *
+ * `serve` starts the local test API so a dApp can exercise its real runner
+ * integration end to end: new EthernityCloudRunner('LOCAL') in
+ * @ethernity-cloud/runner >= 0.3.6 executes every run() against this API
+ * instead of the blockchain.
+ *
+ * Exit code 0 on TaskStatus SUCCESS, 1 otherwise.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const crypto = require('crypto');
+
+const TASK_STATUS_NAMES = {
+  0: 'SUCCESS',
+  1: 'SYSTEM_ERROR',
+  2: 'KEY_ERROR',
+  3: 'SYNTAX_WARNING',
+  4: 'BASE_EXCEPTION',
+  5: 'PAYLOAD_NOT_DEFINED',
+  6: 'PAYLOAD_CHECKSUM_ERROR',
+  7: 'INPUT_CHECKSUM_ERROR',
+  8: 'EVAL_ERROR',
+  28: 'IMPORT_ERROR',
+  32: 'CONFIG_ERROR',
+};
+
+const VENDORED_SRC = path.join(__dirname, 'nodenithy', 'build', 'securelock', 'src');
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(from, to);
+    else fs.copyFileSync(from, to);
+  }
+}
+
+/* Stage the executor + the project's backend the way ecld-build does inside
+ * the enclave image, then load the REAL executor from the staged copy. */
+function loadExecutor(projectSrc) {
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'ecld-test-'));
+  for (const f of ['etny_exec.js', 'task_status.js']) {
+    fs.copyFileSync(path.join(VENDORED_SRC, f), path.join(stage, f));
+  }
+  const backendDir = path.join(projectSrc, 'serverless');
+  const backendJs = path.join(backendDir, 'backend.js');
+  if (fs.existsSync(backendJs)) {
+    copyDir(backendDir, path.join(stage, 'serverless'));
+    console.log(`backend : ${backendJs}`);
+  } else if (fs.existsSync(path.join(backendDir, 'backend.py'))) {
+    console.log('backend : backend.py found — this is a Pynithy project; use');
+    console.log('          ecld-test from ethernity-cloud-sdk-py instead.');
+    console.log('          Continuing with bare globals (stock-enclave mode).');
+  } else {
+    console.log('backend : none found — running with bare globals, like a stock enclave');
+  }
+  return require(path.join(stage, 'etny_exec.js'));
+}
+
+function runTask(executor, payload, input) {
+  const [code, resultRaw] = executor.executeTask(payload, input || '');
+  const result = typeof resultRaw === 'string' ? resultRaw : JSON.stringify(resultRaw);
+  const checksum = crypto.createHash('sha256').update(result, 'utf8').digest('hex');
+  const challenge = Array.from({ length: 20 }, () =>
+    'abcdefghijklmnopqrstuvwxyz0123456789'[Math.floor(Math.random() * 36)]
+  ).join('');
+  return {
+    task_code: code,
+    task_code_name: TASK_STATUS_NAMES[code] || `UNKNOWN_${code}`,
+    result,
+    checksum,
+    enclave_challenge: challenge,
+    result_string: `v3:${code}:${checksum}:${challenge}:`,
+  };
+}
+
+function serve(executor, host, port) {
+  const server = http.createServer((req, res) => {
+    const send = (status, obj) => {
+      const body = JSON.stringify(obj);
+      res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Headers': 'Content-Type',
+      });
+      res.end(body);
+    };
+    if (req.method === 'OPTIONS') return send(204, {});
+    if (req.method === 'GET' && req.url === '/v1/health') {
+      // Probe with an expression that lists scope? Keep it simple: report ok.
+      return send(200, { status: 'ok', backend: serve.backendFunctions || [] });
+    }
+    if (req.method === 'POST' && req.url === '/v1/task') {
+      let raw = '';
+      req.on('data', (c) => { raw += c; });
+      req.on('end', () => {
+        try {
+          const body = JSON.parse(raw || '{}');
+          if (typeof body.payload !== 'string' || !body.payload.trim()) {
+            return send(400, { error: 'payload (string) is required' });
+          }
+          let input = body.input;
+          if (input !== undefined && input !== null && typeof input !== 'string') {
+            input = JSON.stringify(input);
+          }
+          const out = runTask(executor, body.payload, input);
+          console.log(`[local-api] task -> ${out.task_code} (${out.task_code_name})`);
+          return send(200, out);
+        } catch (e) {
+          if (e instanceof SyntaxError) return send(400, { error: 'invalid JSON body' });
+          return send(500, { error: e.message });
+        }
+      });
+      return;
+    }
+    send(404, { error: 'not found' });
+  });
+  server.listen(port, host, () => {
+    console.log(`[local-api] listening on http://${host}:${port}  (POST /v1/task, GET /v1/health)`);
+  });
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const opts = { src: 'src', host: '127.0.0.1', port: 8745 };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--file' || a === '-f') opts.file = argv[++i];
+    else if (a === '--input' || a === '-i') opts.inputFile = argv[++i];
+    else if (a === '--input-text') opts.inputText = argv[++i];
+    else if (a === '--src') opts.src = argv[++i];
+    else if (a === '--host') opts.host = argv[++i];
+    else if (a === '--port') opts.port = parseInt(argv[++i], 10);
+    else positional.push(a);
+  }
+
+  const projectSrc = path.resolve(opts.src);
+  const executor = loadExecutor(projectSrc);
+  // Record the backend's exported names once for /v1/health.
+  try {
+    serve.backendFunctions = Object.keys(require(path.join(projectSrc, 'serverless', 'backend.js')));
+  } catch (e) {
+    serve.backendFunctions = [];
+  }
+
+  if (positional[0] === 'serve') {
+    return serve(executor, opts.host, opts.port);
+  }
+
+  let payload;
+  if (opts.file) payload = fs.readFileSync(opts.file, 'utf8');
+  else if (positional.length) payload = positional.join(' ');
+  else {
+    console.error("usage: ecld-test 'hello(\"World\")' | ecld-test --file payload.js | ecld-test serve");
+    process.exit(2);
+  }
+
+  let input = null;
+  if (opts.inputFile && opts.inputText !== undefined) {
+    console.error('--input and --input-text are mutually exclusive');
+    process.exit(2);
+  }
+  if (opts.inputFile) input = fs.readFileSync(opts.inputFile, 'utf8');
+  else if (opts.inputText !== undefined) input = opts.inputText;
+
+  console.log(`payload : ${JSON.stringify(payload)}`);
+  console.log(`input   : ${input === null ? '<empty>' : JSON.stringify(input.slice(0, 80))}`);
+  const out = runTask(executor, payload, input);
+  console.log(`task code: ${out.task_code} (${out.task_code_name})`);
+  console.log(`result   : ${JSON.stringify(out.result)}`);
+  if (out.task_code !== 0) {
+    console.log('\nThis is exactly what the network would write on-chain — the failed');
+    console.log('attempt would still cost gas. Fix locally, then submit.');
+  }
+  process.exit(out.task_code === 0 ? 0 : 1);
+}
+
+main();