@ethernity-cloud/sdk-js 1.5.11 → 1.5.12

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

@@ -101,6 +101,11 @@ const CONTAINER_MARK = '_ecld_state';
 
 class StatePermissionError extends Error {}
 
+// A commit's idempotency nonce was already used: the dApp supplied `nonce` on
+// commit() and it is not greater than the last accepted nonce for the key --
+// a duplicate (or out-of-order) submission. The state was NOT changed.
+class StateNonceError extends Error {}
+
 function unwrapStored(stored) {
   if (stored && typeof stored === 'object' && stored[CONTAINER_MARK] === 1) {
     return [stored.acl || null, stored.data];
@@ -108,13 +113,25 @@ function unwrapStored(stored) {
   return [null, stored];
 }
 
-function wrapStored(acl, data, committedBy = null) {
+/** Last accepted idempotency nonce carried by a stored blob (0 if none). */
+function storedNonce(stored) {
+  if (stored && typeof stored === 'object' && stored[CONTAINER_MARK] === 1) {
+    const n = parseInt(stored.nonce, 10);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
+
+function wrapStored(acl, data, committedBy = null, nonce = null) {
   // For owned state, bind the authoring caller (committedBy) INTO the blob, so
   // it lands in the CID -- the field the securelock signs -- making the caller
   // cryptographically bound to the commit, not merely a re-stampable sidecar.
-  if (!acl) return data;                 // unowned keeps the legacy shape
-  const container = { [CONTAINER_MARK]: 1, acl, data };
+  // Unowned state keeps the legacy bare shape -- unless a nonce must be
+  // carried, which forces the container so the nonce survives in the blob.
+  if (!acl && nonce == null) return data;
+  const container = { [CONTAINER_MARK]: 1, acl: acl || null, data };
   if (committedBy) container.committedBy = committedBy;
+  if (nonce != null) container.nonce = Math.trunc(nonce);
   return container;
 }
 
@@ -328,6 +345,15 @@ class StateRegistry {
     return esr_wallet.deriveWalletAddress(_identityPriv);
   }
 
+  /**
+   * Alias of walletAddress — the ENCLAVE's own on-chain address (its identity,
+   * and the namespace all its state keys live under). Preferred name in new
+   * code; walletAddress remains for compatibility.
+   */
+  get enclaveAddress() {
+    return this.walletAddress;
+  }
+
   _signer() {
     // Reuse esr_wallet's derivation rather than repeating it here: two copies
     // would eventually disagree, and the address a client funds would stop
@@ -368,11 +394,11 @@ class StateRegistry {
     return data;
   }
 
-  /** [acl, data, version, cid] for `key`; NO permission check here. */
+  /** [acl, data, version, cid, nonce] for `key`; NO permission check here. */
   async _readContainer(key, fallback = {}) {
     const [cid, version] = await this._contract().getState(this.walletAddress, keyHash(key));
     if (!version || !cid) {
-      return [null, fallback, 0, null];
+      return [null, fallback, 0, null, 0];
     }
     if (!looksLikeCID(cid)) {
       throw new Error(
@@ -383,7 +409,23 @@ class StateRegistry {
     const blob = await this._fetch(key, cid);
     const stored = JSON.parse(decrypt(blob).toString('utf8'));
     const [acl, data] = unwrapStored(stored);
-    return [acl, data, Number(version), cid];
+    return [acl, data, Number(version), cid, storedNonce(stored)];
+  }
+
+  /**
+   * The last accepted idempotency nonce for `key` (0 if none was ever used).
+   * A dApp that wants duplicate suppression reads this, picks a greater value
+   * (e.g. +1, or a timestamp), and passes it to commit(..., { nonce }).
+   */
+  async getNonce(key) {
+    const [acl, , , , nonce] = await this._readContainer(key);
+    if (!canRead(acl)) {
+      throw new StatePermissionError(
+        `caller ${_taskCaller || '<anonymous>'} has no read permission on ` +
+          `state key '${key}' (owner: ${acl.owner})`
+      );
+    }
+    return nonce;
   }
 
   /**
@@ -393,7 +435,14 @@ class StateRegistry {
    * 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) {
+  async commit(key, mutate, opts = 3) {
+    // Back-compat: the third arg used to be `attempts` (a number); it may now
+    // also be { attempts, nonce }. `nonce` is an idempotency guard the dApp
+    // controls: it must be STRICTLY GREATER than the last accepted nonce for
+    // the key (see getNonce). A duplicate or stale nonce throws
+    // StateNonceError and the state is NOT changed.
+    const { attempts = 3, nonce = null } =
+      typeof opts === 'number' ? { attempts: opts } : (opts || {});
     const transform = async (acl, data) => {
       if (!canWrite(acl)) {
         throw new StatePermissionError(
@@ -405,7 +454,7 @@ class StateRegistry {
       if (!nextAcl && _taskCaller) nextAcl = newAcl(_taskCaller); // first-writer-owns
       return [nextAcl, await mutate(data)];
     };
-    const [, newData] = await this._commitTransform(key, transform, attempts);
+    const [, newData] = await this._commitTransform(key, transform, attempts, nonce);
     return newData;
   }
 
@@ -415,16 +464,33 @@ class StateRegistry {
    * data while unowned). On a version race we re-read and retry, so
    * concurrent tasks cannot silently lose updates.
    */
-  async _commitTransform(key, transform, attempts = 3) {
+  async _commitTransform(key, transform, attempts = 3, nonce = null) {
     let lastError = null;
     for (let attempt = 0; attempt < attempts; attempt += 1) {
       // eslint-disable-next-line no-await-in-loop
-      const [acl, data, currentVersion] = await this._readContainer(key);
+      const [acl, data, currentVersion, , priorNonce] = await this._readContainer(key);
+      // The nonce check re-runs on every retry against the freshly read state,
+      // so a racing commit that consumed the same nonce fails this one.
+      let finalNonce;
+      if (nonce != null) {
+        const n = Math.trunc(nonce);
+        if (n <= priorNonce) {
+          throw new StateNonceError(
+            `nonce ${n} was already used for state key '${key}' (last accepted: ` +
+              `${priorNonce}); duplicate commit suppressed, state unchanged`
+          );
+        }
+        finalNonce = n;
+      } else {
+        // Preserve the stored nonce so a nonce-less commit cannot reset the
+        // guard and reopen replays.
+        finalNonce = priorNonce > 0 ? priorNonce : null;
+      }
       // eslint-disable-next-line no-await-in-loop
       const [nextAcl, newData] = await transform(acl, data, currentVersion);
       // Bind the authoring caller into the blob (hence the CID/signature) for
       // owned state.
-      const stored = wrapStored(nextAcl, newData, nextAcl ? _taskCaller : null);
+      const stored = wrapStored(nextAcl, newData, nextAcl ? _taskCaller : null, finalNonce);
 
       const blob = encrypt(Buffer.from(JSON.stringify(stored), 'utf8'));
       // Compute the CID from OUR bytes — never accept one from the node.
@@ -622,6 +688,14 @@ async function esrAcl(key) {
 
 function setTaskCaller(caller) { _taskCaller = normAddr(caller); }
 
+/**
+ * The last accepted idempotency nonce for `key` (0 if none). See
+ * StateRegistry.getNonce / commit(key, mutate, { nonce }).
+ */
+async function esrNonce(key) {
+  return new StateRegistry().getNonce(key);
+}
+
 module.exports = {
   StateRegistry,
   configure,
@@ -632,12 +706,14 @@ module.exports = {
   setTaskCaller,
   restampLedgerCaller,
   StatePermissionError,
+  StateNonceError,
   esrGrant,
   esrRevoke,
   esrSetPublicRead,
   esrTransfer,
   esrOwner,
   esrAcl,
+  esrNonce,
   // local-testing hooks (esr_local only)
   setContractOverride,
   setLocalCommitApply,

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

@@ -1,225 +1,230 @@
-const fs = require('fs');
-const path = require('path');
-const { TaskStatus } = require('./task_status');
-
-// Load EVERY export of ./serverless/backend into the payload's scope. The
-// backend is copied next to this file by ecld-build (and staged the same way
-// by ecld-test locally), so one code path serves both the enclave and local
-// testing. Previously only a function literally named `hello` was reachable
-// (hardcoded destructure); any other exported function threw ReferenceError.
-// A missing backend leaves only ___etny_result___ in scope, which is the
-// stock-enclave behaviour.
-let backendFunctions = {};
-// If the backend fails to load, remember WHY. A silently-swallowed failure
-// (missing npm module, bad require inside backend.js) makes every task die
-// later with a misleading "X is not defined". Only a genuinely absent backend
-// stays silent — that is the stock-enclave configuration.
-let backendImportError = null;
-try {
-    backendFunctions = { ...require('./serverless/backend') };
-} catch (e) {
-    backendFunctions = {};
-    // MODULE_NOT_FOUND messages embed the whole require stack (which always
-    // mentions serverless/backend.js), so parse out WHICH module is missing:
-    // only a missing backend module itself means "no backend shipped".
-    const m = /Cannot find module '([^']+)'/.exec(e.message || '');
-    const missingBackendItself =
-        e.code === 'MODULE_NOT_FOUND' && m && /serverless[\\/]backend/.test(m[1]);
-    if (!missingBackendItself) {
-        backendImportError = `${e.name || 'Error'}: ${(e.message || '').split('\n')[0]}`;
-    }
-}
-
-/**
- * Automatic encoding for task results (single code path for all results):
- * JSON-serializable values ride as JSON, strings as text, bytes-like as
- * base64. Anything else is JSON-stringified with a String() fallback -- a
- * task result never fails on encoding.
- */
-function encodeResultData(data) {
-    if (Buffer.isBuffer(data) || data instanceof Uint8Array) {
-        return ['base64', Buffer.from(data).toString('base64')];
-    }
-    if (typeof data === 'string') {
-        return ['text', data];
-    }
-    try {
-        JSON.stringify(data);
-        return ['json', data === undefined ? null : data];
-    } catch (e) {
-        try {
-            return ['json', JSON.parse(JSON.stringify(data, (k, v) =>
-                typeof v === 'bigint' || typeof v === 'function' ? String(v) : v))];
-        } catch (e2) {
-            return ['text', String(data)];
-        }
-    }
-}
-
-/**
- * Return a task result (THE way to end a task).
- *
- * Builds the structured result envelope:
- *   { ecld: 1, type: 'json'|'text'|'base64', data: ..., esr: ... }
- *
- * - `data` is encoded automatically (see encodeResultData).
- * - `state: true` (default) attaches the ESR state of every key this task
- *   touched; `state: 'meta'` attaches {key, version, cid} without the state
- *   payload; `state: false` attaches nothing.
- * - `keys: [...]` restricts the attachment to those keys (already-touched
- *   only -- to attach an untouched key, use the async esrFetch helper).
- *
- * ESR attachment is best-effort: an ESR-disabled build (or any attachment
- * error) yields esr: null, never a failed task.
- */
-function ecldResult(data = null, { state = true, keys = null } = {}) {
-    const [type, encoded] = encodeResultData(data);
-    const envelope = { ecld: 1, type, data: encoded, esr: null };
-    if (state || keys) {
-        try {
-            // eslint-disable-next-line global-require
-            const ecldState = require('./ecld_state');
-            envelope.esr = ecldState.ledgerSnapshot(state === true, keys);
-        } catch (e) {
-            envelope.esr = null;
-        }
-    }
-    return [0, JSON.stringify(envelope)];
-}
-
-/** Legacy alias: same builder, ESR attachment off -- today's behavior. */
-function ___etny_result___(data) {
-    return ecldResult(data, { state: false });
-}
-
-/**
- * Standard state-fetch task body: awaits the reads (populating the task
- * ledger), then attaches them. The runner's cache-gated read submits this on
- * a cache miss: `await esrFetch('profile-7')`.
- */
-async function esrFetch(...keys) {
-    try {
-        // eslint-disable-next-line global-require
-        const { StateRegistry } = require('./ecld_state');
-        const reg = new StateRegistry();
-        for (const k of keys) {
-            // eslint-disable-next-line no-await-in-loop
-            await reg.get(k);
-        }
-    } catch (e) { /* ESR-disabled build: esr stays null */ }
-    return ecldResult(null, { keys: keys.length ? keys : null });
-}
-
-// Names of *_ADDRESS-style enclave config vars that are set but EMPTY.
-// The enclave is sealed: env can only come from the image, so a present-but-
-// empty required value is always a build/render defect, never a runtime
-// choice. ESR_* vars only exist when the project enabled ESR at build time.
-function emptyRequiredConfig() {
-    const required = ['ESR_CONTRACT_ADDRESS'];
-    return required.filter(
-        (name) => name in process.env && !String(process.env[name]).trim()
-    );
-}
-
-async function executeTask(payload, input) {
-    const missing = emptyRequiredConfig();
-    if (missing.length) {
-        return [
-            TaskStatus.CONFIG_ERROR,
-            'ENCLAVE CONFIG ERROR: required value(s) empty inside the enclave: ' +
-            missing.join(', ') +
-            ' | The enclave is sealed, so this value had to be baked at build' +
-            ' time and was not. Re-run ecld-build (it validates ESR config)' +
-            ' and republish.'
-        ];
-    }
-    if (backendImportError !== null) {
-        return [
-            TaskStatus.IMPORT_ERROR,
-            'BACKEND IMPORT ERROR: ' + backendImportError +
-            ' | The serverless backend failed to load inside the enclave, so none of its' +
-            ' functions are available. Common causes: a module missing from the enclave' +
-            ' image dependencies, or a bad require() inside backend.js.'
-        ];
-    }
-    const scope = {
-        '___etny_result___': ___etny_result___,   // legacy alias (no ESR)
-        'ecldResult': ecldResult,                 // the result API
-        'esrFetch': esrFetch,                     // standard state-fetch task
-        ...backendFunctions,
-    };
-    // State ownership / ACL API (present only in ESR-enabled builds). Enforced
-    // inside ecld_state against the trustedzone-attested caller.
-    try {
-        // eslint-disable-next-line global-require
-        const ecldState = require('./ecld_state');
-        for (const name of ['taskCaller', 'esrGrant', 'esrRevoke',
-            'esrSetPublicRead', 'esrTransfer', 'esrOwner', 'esrAcl']) {
-            if (!(name in scope)) scope[name] = ecldState[name];
-        }
-    } catch (e) { /* non-ESR build */ }
-    return exec(payload, input, scope);
-}
-
-async function exec(payload, input, globals = null) {
-    try {
-        if (payload && payload !== "") {
-            const scope = globals || {};
-            if (input && input !== "") {
-                scope['___etny_data_set___'] = input;
-            }
-            // `with` exposes every backend function and ___etny_data_set___ to
-            // the payload by bare name — matching how payloads are written
-            // (e.g. `processData(___etny_data_set___)`).
-            with (scope) {
-                // ESR reads/commits are async, so a state-using payload
-                // (`esrIncrement()`, `await reg.commit(...)`) evaluates to a
-                // Promise. Await it so the finished value -- not the pending
-                // Promise -- is what gets wrapped. Non-async payloads await to
-                // themselves, so this is transparent for plain results.
-                const value = await eval(payload);
-                // A payload that called ecldResult/___etny_result___ itself
-                // already holds the finished [0, envelopeJson] tuple -- pass
-                // it through instead of wrapping the result a second time.
-                if (Array.isArray(value) && value.length === 2 &&
-                    value[0] === 0 && typeof value[1] === 'string') {
-                    return value;
-                }
-                return ___etny_result___(value);
-            }
-        } else {
-            return [TaskStatus.PAYLOAD_NOT_DEFINED, 'Could not find the source file to execute'];
-        }
-
-        // return [TaskStatus.SUCCESS, 'TASK EXECUTED SUCCESSFULLY'];
-    } catch (error) {
-        // A task returns its result by RETURNING (via ___etny_result___), not by
-        // throwing, so anything caught here is a genuine failure. In every branch
-        // deliver the FULL stack trace to the data owner AS THE RESULT (visible in
-        // their runner output) and never crash the enclave -- always return a
-        // normal [code, data] tuple so the trustedzone stops waiting. Honor the
-        // embedded-result SUCCESS (code 0) case first.
-        try {
-            if (error && error.args && error.args[0] && error.args[0][0] === 0) {
-                return [TaskStatus.SUCCESS, error.args[0][1]];
-            }
-        } catch (e) { /* fall through to failure reporting */ }
-
-        const detail = (error && (error.stack || error.message)) || String(error);
-        console.error('Error in payload execution -- full stack follows:\n' + detail);
-
-        if (error instanceof ReferenceError) {
-            return [TaskStatus.SYSTEM_ERROR, 'SYSTEM_ERROR (ReferenceError): ' + detail];
-        } else if (error instanceof EvalError) {
-            return [TaskStatus.KEY_ERROR, 'KEY_ERROR (EvalError): ' + detail];
-        } else if (error instanceof SyntaxError) {
-            return [TaskStatus.SYNTAX_WARNING, 'SYNTAX_WARNING (SyntaxError): ' + detail];
-        } else {
-            return [TaskStatus.BASE_EXCEPTION, 'BASE_EXCEPTION: ' + detail];
-        }
-    }
-}
-
-module.exports = {
-    executeTask
-};
+const fs = require('fs');
+const path = require('path');
+const { TaskStatus } = require('./task_status');
+
+// Load EVERY export of ./serverless/backend into the payload's scope. The
+// backend is copied next to this file by ecld-build (and staged the same way
+// by ecld-test locally), so one code path serves both the enclave and local
+// testing. Previously only a function literally named `hello` was reachable
+// (hardcoded destructure); any other exported function threw ReferenceError.
+// A missing backend leaves only ___etny_result___ in scope, which is the
+// stock-enclave behaviour.
+let backendFunctions = {};
+// If the backend fails to load, remember WHY. A silently-swallowed failure
+// (missing npm module, bad require inside backend.js) makes every task die
+// later with a misleading "X is not defined". Only a genuinely absent backend
+// stays silent — that is the stock-enclave configuration.
+let backendImportError = null;
+try {
+    backendFunctions = { ...require('./serverless/backend') };
+} catch (e) {
+    backendFunctions = {};
+    // MODULE_NOT_FOUND messages embed the whole require stack (which always
+    // mentions serverless/backend.js), so parse out WHICH module is missing:
+    // only a missing backend module itself means "no backend shipped".
+    const m = /Cannot find module '([^']+)'/.exec(e.message || '');
+    const missingBackendItself =
+        e.code === 'MODULE_NOT_FOUND' && m && /serverless[\\/]backend/.test(m[1]);
+    if (!missingBackendItself) {
+        backendImportError = `${e.name || 'Error'}: ${(e.message || '').split('\n')[0]}`;
+    }
+}
+
+/**
+ * Automatic encoding for task results (single code path for all results):
+ * JSON-serializable values ride as JSON, strings as text, bytes-like as
+ * base64. Anything else is JSON-stringified with a String() fallback -- a
+ * task result never fails on encoding.
+ */
+function encodeResultData(data) {
+    if (Buffer.isBuffer(data) || data instanceof Uint8Array) {
+        return ['base64', Buffer.from(data).toString('base64')];
+    }
+    if (typeof data === 'string') {
+        return ['text', data];
+    }
+    try {
+        JSON.stringify(data);
+        return ['json', data === undefined ? null : data];
+    } catch (e) {
+        try {
+            return ['json', JSON.parse(JSON.stringify(data, (k, v) =>
+                typeof v === 'bigint' || typeof v === 'function' ? String(v) : v))];
+        } catch (e2) {
+            return ['text', String(data)];
+        }
+    }
+}
+
+/**
+ * Return a task result (THE way to end a task).
+ *
+ * Builds the structured result envelope:
+ *   { ecld: 1, type: 'json'|'text'|'base64', data: ..., esr: ... }
+ *
+ * - `data` is encoded automatically (see encodeResultData).
+ * - `state: true` (default) attaches the ESR state of every key this task
+ *   touched; `state: 'meta'` attaches {key, version, cid} without the state
+ *   payload; `state: false` attaches nothing.
+ * - `keys: [...]` restricts the attachment to those keys (already-touched
+ *   only -- to attach an untouched key, use the async esrFetch helper).
+ *
+ * ESR attachment is best-effort: an ESR-disabled build (or any attachment
+ * error) yields esr: null, never a failed task.
+ */
+function ecldResult(data = null, { state = true, keys = null } = {}) {
+    const [type, encoded] = encodeResultData(data);
+    const envelope = { ecld: 1, type, data: encoded, esr: null };
+    if (state || keys) {
+        try {
+            // eslint-disable-next-line global-require
+            const ecldState = require('./ecld_state');
+            envelope.esr = ecldState.ledgerSnapshot(state === true, keys);
+        } catch (e) {
+            envelope.esr = null;
+        }
+    }
+    return [0, JSON.stringify(envelope)];
+}
+
+/** Legacy alias: same builder, ESR attachment off -- today's behavior. */
+function ___etny_result___(data) {
+    return ecldResult(data, { state: false });
+}
+
+/**
+ * Standard state-fetch task body: awaits the reads (populating the task
+ * ledger), then attaches them. The runner's cache-gated read submits this on
+ * a cache miss: `await esrFetch('profile-7')`.
+ */
+async function esrFetch(...keys) {
+    try {
+        // eslint-disable-next-line global-require
+        const { StateRegistry } = require('./ecld_state');
+        const reg = new StateRegistry();
+        for (const k of keys) {
+            // eslint-disable-next-line no-await-in-loop
+            await reg.get(k);
+        }
+    } catch (e) { /* ESR-disabled build: esr stays null */ }
+    return ecldResult(null, { keys: keys.length ? keys : null });
+}
+
+// Names of *_ADDRESS-style enclave config vars that are set but EMPTY.
+// The enclave is sealed: env can only come from the image, so a present-but-
+// empty required value is always a build/render defect, never a runtime
+// choice. ESR_* vars only exist when the project enabled ESR at build time.
+function emptyRequiredConfig() {
+    const required = ['ESR_CONTRACT_ADDRESS'];
+    return required.filter(
+        (name) => name in process.env && !String(process.env[name]).trim()
+    );
+}
+
+async function executeTask(payload, input) {
+    const missing = emptyRequiredConfig();
+    if (missing.length) {
+        return [
+            TaskStatus.CONFIG_ERROR,
+            'ENCLAVE CONFIG ERROR: required value(s) empty inside the enclave: ' +
+            missing.join(', ') +
+            ' | The enclave is sealed, so this value had to be baked at build' +
+            ' time and was not. Re-run ecld-build (it validates ESR config)' +
+            ' and republish.'
+        ];
+    }
+    if (backendImportError !== null) {
+        return [
+            TaskStatus.IMPORT_ERROR,
+            'BACKEND IMPORT ERROR: ' + backendImportError +
+            ' | The serverless backend failed to load inside the enclave, so none of its' +
+            ' functions are available. Common causes: a module missing from the enclave' +
+            ' image dependencies, or a bad require() inside backend.js.'
+        ];
+    }
+    const scope = {
+        '___etny_result___': ___etny_result___,   // legacy alias (no ESR)
+        'ecldResult': ecldResult,                 // the result API
+        'esrFetch': esrFetch,                     // standard state-fetch task
+        ...backendFunctions,
+    };
+    // State ownership / ACL API (present only in ESR-enabled builds). Enforced
+    // inside ecld_state against the trustedzone-attested caller.
+    try {
+        // eslint-disable-next-line global-require
+        const ecldState = require('./ecld_state');
+        for (const name of ['taskCaller', 'esrGrant', 'esrRevoke',
+            'esrSetPublicRead', 'esrTransfer', 'esrOwner', 'esrAcl', 'esrNonce']) {
+            if (!(name in scope)) scope[name] = ecldState[name];
+        }
+    } catch (e) { /* non-ESR build */ }
+    return exec(payload, input, scope);
+}
+
+async function exec(payload, input, globals = null) {
+    try {
+        if (payload && payload !== "") {
+            const scope = globals || {};
+            if (input && input !== "") {
+                scope['___etny_data_set___'] = input;
+            }
+            // `with` exposes every backend function and ___etny_data_set___ to
+            // the payload by bare name — matching how payloads are written
+            // (e.g. `processData(___etny_data_set___)`).
+            with (scope) {
+                // ESR reads/commits are async, so a state-using payload
+                // (`esrIncrement()`, `await reg.commit(...)`) evaluates to a
+                // Promise. Await it so the finished value -- not the pending
+                // Promise -- is what gets wrapped. Non-async payloads await to
+                // themselves, so this is transparent for plain results.
+                const value = await eval(payload);
+                // A payload that called ecldResult/___etny_result___ itself
+                // already holds the finished [0, envelopeJson] tuple -- pass
+                // it through instead of wrapping the result a second time.
+                if (Array.isArray(value) && value.length === 2 &&
+                    value[0] === 0 && typeof value[1] === 'string') {
+                    return value;
+                }
+                return ___etny_result___(value);
+            }
+        } else {
+            return [TaskStatus.PAYLOAD_NOT_DEFINED, 'Could not find the source file to execute'];
+        }
+
+        // return [TaskStatus.SUCCESS, 'TASK EXECUTED SUCCESSFULLY'];
+    } catch (error) {
+        // A task returns its result by RETURNING (via ___etny_result___), not by
+        // throwing, so anything caught here is a genuine failure. In every branch
+        // deliver the FULL stack trace to the data owner AS THE RESULT (visible in
+        // their runner output) and never crash the enclave -- always return a
+        // normal [code, data] tuple so the trustedzone stops waiting. Honor the
+        // embedded-result SUCCESS (code 0) case first.
+        try {
+            if (error && error.args && error.args[0] && error.args[0][0] === 0) {
+                return [TaskStatus.SUCCESS, error.args[0][1]];
+            }
+        } catch (e) { /* fall through to failure reporting */ }
+
+        // A duplicate-suppressed commit (StateNonceError) gets its own task
+        // code so the dApp can distinguish "already applied" from a failure.
+        if (error && error.constructor && error.constructor.name === 'StateNonceError') {
+            return [TaskStatus.ESR_NONCE_VIOLATION, 'ESR_NONCE_VIOLATION: ' + error.message];
+        }
+        const detail = (error && (error.stack || error.message)) || String(error);
+        console.error('Error in payload execution -- full stack follows:\n' + detail);
+
+        if (error instanceof ReferenceError) {
+            return [TaskStatus.SYSTEM_ERROR, 'SYSTEM_ERROR (ReferenceError): ' + detail];
+        } else if (error instanceof EvalError) {
+            return [TaskStatus.KEY_ERROR, 'KEY_ERROR (EvalError): ' + detail];
+        } else if (error instanceof SyntaxError) {
+            return [TaskStatus.SYNTAX_WARNING, 'SYNTAX_WARNING (SyntaxError): ' + detail];
+        } else {
+            return [TaskStatus.BASE_EXCEPTION, 'BASE_EXCEPTION: ' + detail];
+        }
+    }
+}
+
+module.exports = {
+    executeTask
+};