@ethernity-cloud/sdk-js 1.7.0 → 1.7.7

package/README.md

@@ -41,19 +41,22 @@ The sdk has been tested on the following operating systems:
 - Bloxberg:
     - Testnet - tested and working. CAS-attested: the securelock is
       provisioned by the ethernity-cas validator set exactly as on mainnet.
-      `ecld-publish` registers the securelock session on-chain in the
-      SessionRegistry (`0xcb1F389b...`, see `cas/config.js`), resolves a CAS
-      from the ValidatorRegistry (`0xa821b36F...`, or `ECLD_CAS_ADDR=host:port`)
+      `ecld-publish` registers the image in the ImageRegistry
+      (ECImageRegistryV3, `0xa372a6e1...`) before anything discloses its
+      name, which makes the name the publishing wallet's; then registers the
+      securelock session on-chain in the SessionRegistry (`0x44442968...`, see
+      `cas/config.js`), which takes it only from that wallet, resolves a CAS
+      from the ValidatorRegistry (`0x0014aB10...`, or `ECLD_CAS_ADDR=host:port`)
       for the compose and the certificate harvest, takes the trustedzone
-      session name from the ImageRegistry (ECImageRegistryV2,
-      `0x99A84C62...`), and links the session to the published image. `ecld-build` signs the securelock `--production`.
+      session name from the ImageRegistry, and links the session to the
+      published image. `ecld-build` signs the securelock `--production`.
       Harvesting the certificate needs SGX.
     - Testnet Unsafe - the unsafe network beside the testnet (see below).
     - Mainnet - to be provided during the following updates
 - LitVM:
     - LiteForge - CAS-attested the same way, by LitVM's own ethernity-cas
       validator set (SessionRegistry `0x8ad24b3F...`, ValidatorRegistry
-      `0x2E27677f...`).
+      `0xbE3759f3...`).
     - LiteForge Unsafe - the unsafe network beside LiteForge (see below).
 - Polyhon:
     - Amoy Testnet - to be provided during the following updates
@@ -108,6 +111,27 @@ sets the enclave heap (default `1024M`).
   npm run ecld-publish
   ```
   Required after build, to build and integrate the secure certificates that will be used during executions and to register the project to the Ethernity Cloud Image Register.
+  `DEVELOPER_FEE` in `.env` is your fee as the image's publisher, in percent of
+  each task's base price (the node's price): the network adds it to what the
+  dApp user pays and pays it to the image's reward address when the task is
+  validated. Default 0; the registry accepts up to 15, and the fee is fixed
+  once the image is registered. The reward address is the publishing wallet
+  unless `REWARD_ADDRESS` names another one; the image's owner can change it
+  later with the registry's `changeImageRewardAddress`.
+
+  How the image reaches the network: unless `.env` names an IPFS API of your
+  own (`IPFS_ENDPOINT` other than the public `ipfs.ethernity.cloud`), the
+  publish runs its own IPFS node in docker (`ipfs/kubo`), adds the image and
+  its compose there and peers it with the network's bootnode, which pins
+  every registered image. On a network whose image registry records images
+  before their certificate (the bloxberg testnet), the publish registers the
+  image from your wallet first (`registerImage`, with your node's address),
+  has the certificate extracted (on your SGX host, or by
+  publickey.ethernity.cloud, which fetches the image from your node or the
+  bootnode and reports its progress) and writes it from the same wallet
+  (`setImageCert`). Keep the publish running until it prints the registration:
+  your node is the image's first source. `ECLD_KUBO_SWARM_PORT` (default
+  4001) is the port your node listens on when it is free.
 
 - **Test (local, no chain)**: To run your backend locally with the enclave's own
   executor — no SGX, no gas, instant — run:
@@ -189,63 +213,63 @@ function hello(msg='World') {
 
 module.exports = { hello };
 ```
-From your frontend application, using the ethernity cloud runner library, you will be calling the function as seen in the below example, where we pass `hello("World");` to be executed on the backend which will run in the Blockchain:
+From your frontend application, using the ethernity cloud runner library (`@ethernity-cloud/runner`, installed by `ecld-init` at the version this SDK depends on), you will be calling the function as seen in the below example, where we pass `hello("World");` to be executed on the backend which will run in the Blockchain. `npm start` runs `src/preStart.mjs` first, which fills the constants at the top from the project's `.env`: the securelock name the dApp is published as, the trustedzone it was built against, the network's token address and chain id, the `-unsafe` network when the dApp runs without a CAS, and the IPFS endpoint.
 ```js
-const AppCss = require('./App.css');
+import './App.css';
 import EthernityCloudRunner from "@ethernity-cloud/runner";
-import {ECEvent, ECRunner, ECStatus} from "@ethernity-cloud/runner/enums";
-import Web3 from 'web3';
+import { ECStatus } from "@ethernity-cloud/runner/enums";
 
+// Filled in from the project's .env by src/preStart.mjs on `npm start`.
 const PROJECT_NAME = "";
+const TRUSTED_ZONE_IMAGE = "";
+const NETWORK_ADDRESS = "";
+const CHAIN_ID = null;
+const UNSAFE_NETWORK = null;
 const IPFS_ENDPOINT = "";
 
+// A call into src/serverless/backend.js; its return value is the task result.
 const code = `hello("World");`;
 
 function App() {
     const executeTask = async () => {
-        const runner = new EthernityCloudRunner();
-        // this is a server provided by Ethernity CLOUD, please bear in mind that you can use your own Decentralized Storage server
-        const ipfsAddress = IPFS_ENDPOINT;
-        runner.initializeStorage(ipfsAddress);
-        console.log(PROJECT_NAME)
-        const onTaskProgress = (e) => {
-            if (e.detail.status === ECStatus.ERROR) {
-                console.error(e.detail.message);
-            } else {
-                console.log(e.detail.message);
-            }
-        };
-
-        const onTaskCompleted = (e) => {
-            console.log(`Task Result: ${e.detail.message.result}`);
-            // display the result in page below the buttons
-            const result = document.createElement("p");
-            result.innerHTML = `Task Result: ${e.detail.message.result}`;
-            document.body.appendChild(result);
+        // The browser wallet (MetaMask) signs and pays for the order.
+        const runner = new EthernityCloudRunner(NETWORK_ADDRESS, {}, CHAIN_ID || undefined);
+        if (UNSAFE_NETWORK) {
+            await runner.setNetwork(...UNSAFE_NETWORK);
         }
-
-        runner.addEventListener(ECEvent.TASK_PROGRESS, onTaskProgress);
-        runner.addEventListener(ECEvent.TASK_COMPLETED, onTaskCompleted);
-
-        await runner.run(PROJECT_NAME,
-                        code,
-                         '',
-                         { taskPrice: 10, cpu: 1, memory: 1, storage: 10, bandwidth: 1, duration: 1, validators: 1 });
+        runner.initializeStorage(IPFS_ENDPOINT);
+
+        // Events are named by task status; detail is { message, status, progress }.
+        runner.addEventListener(ECStatus.DEFAULT, (e) => {
+            console.log(`[${e.detail.progress}] ${e.detail.message}`);
+        });
+        runner.addEventListener(ECStatus.ERROR, (e) => {
+            console.error(e.detail.message);
+        });
+        runner.addEventListener(ECStatus.SUCCESS, async () => {
+            const result = await runner.getResult();
+            console.log(`Task Result: ${result}`);
+            const line = document.createElement("p");
+            line.textContent = `Task Result: ${result}`;
+            document.body.appendChild(line);
+        });
+
+        const resources = { taskPrice: 10, cpu: 1, memory: 1, storage: 10, bandwidth: 1, duration: 1, validators: 1 };
+        await runner.run(resources, PROJECT_NAME, code, '', TRUSTED_ZONE_IMAGE);
     };
+
     const connectWallet = async () => {
-      if (window.ethereum) {
-          window.web3 = new Web3(window.ethereum);
-          try {
-              // Request account access
-              await window.ethereum.request({ method: 'eth_requestAccounts' });
-              console.log("Wallet connected");
-          } catch (error) {
-              console.error("User denied account access");
-          }
-      } else {
-          console.log('Please install MetaMask!');
-      }
-  };
+        if (!window.ethereum) {
+            console.log('Please install MetaMask!');
+            return;
+        }
+        try {
+            await window.ethereum.request({ method: 'eth_requestAccounts' });
+            console.log("Wallet connected");
+        } catch (error) {
+            console.error("User denied account access");
+        }
+    };
 
     return (
         <div className="container">

package/cas/config.js

@@ -14,15 +14,15 @@
 // Kept in sync with etny-{pynithy,nodenithy}/v3/networks.yaml
 // (cas_session_registry_address, validator_registry_address).
 const VALIDATOR_REGISTRY = {
-  'etny-pynithy-testnet': '0xa821b36F378F76c793c436F5f9c9CC36c684eBE5',
-  'etny-nodenithy-testnet': '0xa821b36F378F76c793c436F5f9c9CC36c684eBE5',
-  'ecld-pynithy-litvm-testnet': '0x2E27677fb67531eb09134fE331C27899f87ADe10',
-  'ecld-nodenithy-litvm-testnet': '0x2E27677fb67531eb09134fE331C27899f87ADe10',
+  'etny-pynithy-testnet': '0x0014aB102FEa6b02e3D793FF4b9a0Af309fB4E14',
+  'etny-nodenithy-testnet': '0x0014aB102FEa6b02e3D793FF4b9a0Af309fB4E14',
+  'ecld-pynithy-litvm-testnet': '0xbE3759f327e8643fC5A1717fb2072A0dAcBAD29E',
+  'ecld-nodenithy-litvm-testnet': '0xbE3759f327e8643fC5A1717fb2072A0dAcBAD29E',
 };
 
 const SESSION_REGISTRY = {
-  'etny-pynithy-testnet': '0xcb1F389bF4524d1D61EDcbC24eC1F1F9C3FF4Fa6',
-  'etny-nodenithy-testnet': '0xcb1F389bF4524d1D61EDcbC24eC1F1F9C3FF4Fa6',
+  'etny-pynithy-testnet': '0x444429681fCb26470Cb12B5436E48402cF7478A3',
+  'etny-nodenithy-testnet': '0x444429681fCb26470Cb12B5436E48402cF7478A3',
   'ecld-pynithy-litvm-testnet': '0x8ad24b3F406A41a0F8D3440021792EB203957F43',
   'ecld-nodenithy-litvm-testnet': '0x8ad24b3F406A41a0F8D3440021792EB203957F43',
 };

package/cas/resolver.js

@@ -3,9 +3,13 @@
 // The validators are enumerated from the ValidatorRegistry and their enclave
 // endpoints read from the CasKeyStore the registry names via keyStore() --
 // the same chain data the node's own resolver uses before every task. Only
-// /dns4, /dns, /ip4 and /ip6 endpoints are dialled: the SDK runs on a
-// developer's machine with no Tor proxy. An endpoint is taken only after its
-// REST port answered GET /validator/identity.
+// /dns4, /dns, /ip4 and /ip6 endpoints are used: the SDK runs on a
+// developer's machine with no Tor proxy. The CAS the publish dials is taken
+// only after its REST port answered GET /validator/identity. The CAS the
+// published compose names is the first active validator in registry order,
+// unprobed: the node and the extraction service resolve a CAS again before
+// they run the compose, and a rerun of the same publish renders the same
+// compose while the validator set is unchanged.
 //
 // Multiaddrs advertise the ENCLAVE port; the REST port follows the pairing
 // convention rest = 9081 + (enclave - 19765). Enclave ports outside
@@ -53,23 +57,33 @@ async function identityAnswers(host, restPort, timeoutMs) {
   }
 }
 
-// "host:port" (the ENCLAVE port) of the first active validator whose REST port
-// answers, sweeping from a rotating offset; null when none answered.
-async function resolveCas(rpcUrl, registryAddress, probeTimeoutMs = 10000, startAt = null) {
+// The ValidatorRegistry, the CasKeyStore it names and its validator count.
+async function registry(rpcUrl, registryAddress) {
   const provider = new ethers.providers.JsonRpcProvider({ url: rpcUrl, timeout: 30000 });
   const reg = new ethers.Contract(registryAddress, REGISTRY_ABI, provider);
   const total = (await reg.validatorCount()).toNumber();
-  if (total === 0) return null;
-  const store = new ethers.Contract(await reg.keyStore(), STORE_ABI, provider);
-  const offset = startAt === null ? Math.floor(Math.random() * total) : startAt % total;
-  for (let step = 0; step < total; step++) {
-    const v = await reg.validatorSet((offset + step) % total);
-    if (!(await reg.isValidator(v))) continue;
-    for (const ma of await store.multiaddrsOf(v)) {
-      const parsed = parseMultiaddr(ma);
-      if (!parsed) continue;
-      if (await identityAnswers(parsed.host, restPortFor(parsed.port), probeTimeoutMs)) {
-        return `${parsed.host}:${parsed.port}`;
+  const store = total ? new ethers.Contract(await reg.keyStore(), STORE_ABI, provider) : null;
+  return { reg, store, total };
+}
+
+// The usable endpoints of validator `index` as {host, port} (the ENCLAVE
+// port), or none when it is not an active validator.
+async function endpointsOf({ reg, store }, index) {
+  const v = await reg.validatorSet(index);
+  if (!(await reg.isValidator(v))) return [];
+  return (await store.multiaddrsOf(v)).map(parseMultiaddr).filter(Boolean);
+}
+
+// "host:port" (the ENCLAVE port) of the first active validator whose REST port
+// answers, sweeping from a rotating offset; null when none answered.
+async function resolveCas(rpcUrl, registryAddress, probeTimeoutMs = 10000, startAt = null) {
+  const set = await registry(rpcUrl, registryAddress);
+  if (set.total === 0) return null;
+  const offset = startAt === null ? Math.floor(Math.random() * set.total) : startAt % set.total;
+  for (let step = 0; step < set.total; step++) {
+    for (const { host, port } of await endpointsOf(set, (offset + step) % set.total)) {
+      if (await identityAnswers(host, restPortFor(port), probeTimeoutMs)) {
+        return `${host}:${port}`;
       }
     }
   }
@@ -92,4 +106,21 @@ async function casAddressFor(rpcUrl, registryAddress) {
   return resolved;
 }
 
-module.exports = { parseMultiaddr, restPortFor, identityAnswers, resolveCas, casAddressFor };
+// The CAS the published compose names: ECLD_CAS_ADDR when set, else
+// "host:port" (the ENCLAVE port) of the first active validator in registry
+// order, unprobed. Throws when neither yields one.
+async function publishedCasAddress(rpcUrl, registryAddress) {
+  const override = String(process.env.ECLD_CAS_ADDR || '').trim();
+  if (override) return override;
+  if (!registryAddress) {
+    throw new Error('no ValidatorRegistry is known for this network and ECLD_CAS_ADDR is not set');
+  }
+  const set = await registry(rpcUrl, registryAddress);
+  for (let index = 0; index < set.total; index++) {
+    const [first] = await endpointsOf(set, index);
+    if (first) return `${first.host}:${first.port}`;
+  }
+  throw new Error(`no active validator in ${registryAddress} publishes a usable endpoint`);
+}
+
+module.exports = { parseMultiaddr, restPortFor, identityAnswers, resolveCas, casAddressFor, publishedCasAddress };

package/cas/session_registry.js

@@ -14,11 +14,21 @@
 const crypto = require('crypto');
 const axios = require('axios');
 const { ethers } = require('ethers');
+const { revertReason } = require('../revert.js');
 
+// `latest` and `record` name a version by its record key: a record id
+// (keccak256(abi.encode(name, sessionHash))), or the body's hash on the
+// registries that key records by it. The record holds the body's hash on both.
 const ABI = [
   'function register(bytes32 sessionHash, string name, string bodyCid, string imageCid, uint8 hashAlgo, (string[] tolerate, string[] ignoreAdvisories, string[] mrenclaves, uint16 minIsvSvn, bool debugAllowed, bool skipQuoteVerification) rulesIn) returns (uint32)',
   'function latest(string name) view returns (bytes32)',
-  'function linkImage(bytes32 sessionHash, string imageCid)',
+  'function record(bytes32 id) view returns (bytes32 sessionHash, address creator, string enclaveName, uint32 version, string bodyCid, string imageCid, uint8 hashAlgo, uint64 registeredAt, bool exists)',
+  'function linkImage(bytes32 id, string imageCid)',
+  'error NotCreator(address creator, address caller)',
+  'error DuplicateSession(bytes32 recordId)',
+  'error NotImageNameOwner(string project, address nameOwner, address caller)',
+  'error NotAllowedPublisher(address caller)',
+  'error AmbiguousSecurelockName(string name)',
 ];
 
 const HASH_ALGO_SHA256 = 1;
@@ -78,52 +88,90 @@ function contract(rpcUrl, registryAddress, key) {
   return new ethers.Contract(registryAddress, ABI, signer);
 }
 
+// The latest version of `name`: {id, hash, creator}, or null when it has none.
+async function latestRecord(reg, name) {
+  const id = await reg.latest(name);
+  if (/^0x0+$/.test(id)) return null;
+  const rec = await reg.record(id);
+  return { id, hash: rec.sessionHash.toLowerCase(), creator: rec.creator };
+}
+
+// Send `method(...args)` to the registry. It is simulated first, so a call
+// the registry refuses stops with the registry's reason (`refused` names the
+// call), then sent with its gas estimate plus 30%: a registration's cost
+// grows with the length of the name. The wallet signs for the chain its RPC
+// serves (ethers takes no chainId override on a contract call), so an RPC
+// serving another chain than `chainId` is refused before anything is sent.
+async function send(reg, chainId, refused, method, ...args) {
+  const { chainId: served } = await reg.provider.getNetwork();
+  if (served !== chainId) {
+    throw new Error(`SessionRegistry: the RPC serves chain ${served}, not ${chainId}`);
+  }
+  try {
+    await reg.callStatic[method](...args);
+  } catch (e) {
+    throw new Error(`SessionRegistry refuses ${refused}: ${revertReason(e, reg.interface)}`);
+  }
+  const gas = await reg.estimateGas[method](...args);
+  const tx = await reg[method](...args, {
+    gasLimit: gas.mul(13).div(10), gasPrice: ethers.utils.parseUnits('1', 'mwei'),
+  });
+  const rcpt = await tx.wait();
+  if (rcpt.status !== 1) throw new Error(`SessionRegistry.${method} reverted for ${refused} (tx ${tx.hash})`);
+}
+
 // Pin `body` and register it under its own `name:`. Returns
 // {name, hash, cid, registered}: `registered` is false when the chain already
-// held these exact bytes as the name's latest version.
+// held these exact bytes as the name's latest version, registered by this
+// wallet.
 async function register(rpcUrl, chainId, registryAddress, key, body, ipfsApiUrl, imageCid = '') {
   const { name, rules } = parseNameAndRules(body.toString('utf8'));
   if (!name) throw new Error('the session body has no `name:`');
   const hash = sessionHash(body);
   const reg = contract(rpcUrl, registryAddress, key);
   const cid = await pinBody(ipfsApiUrl, body);
-  if ((await reg.latest(name)).toLowerCase() === hash) {
+  const latest = await latestRecord(reg, name);
+  if (latest && latest.hash === hash && latest.creator.toLowerCase() === (await reg.signer.getAddress()).toLowerCase()) {
     return { name, hash, cid, registered: false };
   }
-  const tx = await reg.register(hash, name, cid, imageCid, HASH_ALGO_SHA256, rules, {
-    gasLimit: 800000, gasPrice: ethers.utils.parseUnits('1', 'mwei'), chainId,
-  });
-  const rcpt = await tx.wait();
-  if (rcpt.status !== 1) {
-    throw new Error(`SessionRegistry.register reverted for ${name} (tx ${tx.hash}): this name's creator may be another wallet, or the SessionRules shape differs from the ABI`);
-  }
+  await send(reg, chainId, name, 'register', hash, name, cid, imageCid, HASH_ALGO_SHA256, rules);
   return { name, hash, cid, registered: true };
 }
 
-// Point the name's latest version at the published image CID.
-async function linkImage(rpcUrl, chainId, registryAddress, key, name, imageCid) {
+// Point the name's latest version at the published image CID. A node behind
+// the chain can answer that a name registered minutes earlier has no record,
+// so the name is read again every 15 seconds for `waitMs` before it is called
+// unregistered.
+async function linkImage(rpcUrl, chainId, registryAddress, key, name, imageCid, waitMs = 600000) {
   const reg = contract(rpcUrl, registryAddress, key);
-  const hash = await reg.latest(name);
-  if (/^0x0+$/.test(hash)) throw new Error(`no registered session named ${name}`);
-  const tx = await reg.linkImage(hash, imageCid, { gasLimit: 300000, gasPrice: ethers.utils.parseUnits('1', 'mwei'), chainId });
-  const rcpt = await tx.wait();
-  if (rcpt.status !== 1) throw new Error(`SessionRegistry.linkImage reverted for ${name} (tx ${tx.hash})`);
+  const deadline = Date.now() + waitMs;
+  let latest = await latestRecord(reg, name);
+  while (!latest) {
+    if (Date.now() >= deadline) throw new Error(`no registered session named ${name}`);
+    await sleep(15000);
+    latest = await latestRecord(reg, name);
+  }
+  await send(reg, chainId, `the link of ${name}`, 'linkImage', latest.id, imageCid);
 }
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-// Block until the chain reports `name` at `hash`, then hold while the
-// validators pick it up: the elected writer's poll (ECAS_SESSION_WATCH_SECS,
-// 60 s) notices the registration and generates the secrets, its recordKey
-// transaction confirms, and the other validators' next poll adopts the
-// recorded blob. The enclave cannot retry and the validator it dials is the
-// node's choice, so the wait covers the LAST validator to adopt.
+// Block until the chain reports `name`'s latest version at body hash `hash`,
+// then hold while the validators pick it up: the elected writer's poll
+// (ECAS_SESSION_WATCH_SECS, 60 s) notices the registration and generates the
+// secrets, its recordKey transaction confirms, and the other validators' next
+// poll adopts the recorded blob. The enclave cannot retry and the validator
+// it dials is the node's choice, so the wait covers the LAST validator to
+// adopt.
 async function waitVisible(rpcUrl, registryAddress, name, hash, timeoutMs = 180000) {
   const reg = contract(rpcUrl, registryAddress, null);
   const deadline = Date.now() + timeoutMs;
   for (;;) {
     let got;
-    try { got = (await reg.latest(name)).toLowerCase(); } catch (e) { got = `(read failed: ${e.message})`; }
+    try {
+      const latest = await latestRecord(reg, name);
+      got = latest ? latest.hash : '(none)';
+    } catch (e) { got = `(read failed: ${e.message})`; }
     if (got === hash.toLowerCase()) {
       console.log(`\t✔  session ${name} visible on chain at ${got}`);
       break;

package/info.js

@@ -46,7 +46,7 @@ const NETWORKS = {
   BLOXBERG_TESTNET: {
     type: 'testnet', chainId: 8995, rpc: 'https://bloxberg.ethernity.cloud',
     protocol: '0x02882F03097fE8cD31afbdFbB5D72a498B41112c',
-    imageRegistry: '0x99A84C624C028bdf0a855A1E9E3f2fcf7275B3D8',
+    imageRegistry: '0xa372a6e1Eb7Fcf343AF6b91E809b900C55001CD1',
     esr: '0x0Ea1728EAE108FD3B9340ae91451348E2Cc6b4E4',
   },
   LITVM_LITEFORGE: {

package/init.js

@@ -28,6 +28,14 @@ const writeEnv = (key, value) => {
   fs.writeFileSync(envFile, content, "utf8");
 };
 
+// The project name is the securelock's image name, and <name>-unsafe on an
+// -unsafe network. ECImageRegistryV3 takes 1 to 128 of [0-9A-Za-z._-], so a
+// project name is at most 121 of them; spaces are written as '_'. It also
+// begins the securelock's session name, <name>_SECURELOCK_V3_..., which the
+// SessionRegistry refuses when "_SECURELOCK_" occurs in it twice, so a project
+// name does not contain "SECURELOCK".
+const PROJECT_NAME_RULE = /^(?!.*SECURELOCK)[0-9A-Za-z._-]{1,121}$/;
+
 const getProjectName = () => {
   return new Promise((resolve) => {
     const askProjectName = () => {
@@ -37,6 +45,11 @@ const getProjectName = () => {
             "Project name cannot be blank. Please enter a valid name.",
           );
           askProjectName();
+        } else if (!PROJECT_NAME_RULE.test(projectName.trim().replace(/ /g, "_"))) {
+          console.log(
+            "A project name is 1 to 121 letters, digits, '.', '-' or '_' (a space becomes '_'), and does not contain SECURELOCK. Please enter a valid name.",
+          );
+          askProjectName();
         } else {
           console.log(`You have chosen the project name: ${projectName}`);
           resolve(projectName);
@@ -310,9 +323,11 @@ const main = async () => {
       );
     }
     console.log("Installing required packages...");
-    // Simulate npm install
+    // The app runs on the runner at the range this SDK depends on; the spec is
+    // quoted because cmd.exe treats a bare ^ as its escape character.
+    const runnerSpec = `@ethernity-cloud/runner@${require("./package.json").dependencies["@ethernity-cloud/runner"]}`;
     execSync(
-      "npm install @ethernity-cloud/runner@0.0.26 @testing-library/jest-dom@5.17.0 @testing-library/react@13.4.0 @testing-library/user-event@13.5.0 react@18.3.1 react-dom@18.3.1 react-scripts@5.0.1 web-vitals@2.1.4 web3@4.9.0 dotenv@16.4.5",
+      `npm install "${runnerSpec}" @testing-library/jest-dom@5.17.0 @testing-library/react@13.4.0 @testing-library/user-event@13.5.0 react@18.3.1 react-dom@18.3.1 react-scripts@5.0.1 web-vitals@2.1.4 dotenv@16.4.5`,
       { stdio: "inherit" },
     );
   } else {

package/localKubo.js

@@ -0,0 +1,160 @@
+// The Kubo a publish runs for its own upload.
+//
+// An image is published by adding it to IPFS and registering its CID. The
+// public write API of ipfs.ethernity.cloud is closing, so a publish without an
+// IPFS endpoint of its own runs a Kubo in docker (the SDK already requires
+// docker), adds the image through that Kubo's HTTP API with the same call the
+// public API received (so a build gives the same CIDs as before), peers the
+// Kubo with the bootnode, whose mirror pins every registered image and from
+// which the certificate extraction service fetches, and stops it once the
+// certificate is on chain. The Kubo listens for the API on the loopback
+// interface only; its swarm port is published when free, so a publisher with
+// a reachable address is also dialed directly.
+const { execFileSync } = require('child_process');
+const net = require('net');
+const axios = require('axios');
+
+const KUBO_IMAGE = process.env.ECLD_KUBO_IMAGE || 'ipfs/kubo:release';
+// The bootnode's IPFS node (ipfs.ethernity.cloud), as the node agents peer with it.
+const BOOTNODE_MULTIADDR = '/dns4/ipfs.ethernity.cloud/tcp/4001/p2p/QmRBc1eBt4hpJQUqHqn6eA8ixQPD3LFcUDsn6coKBQtia5';
+const SWARM_PORT = Number(process.env.ECLD_KUBO_SWARM_PORT || 4001);
+const API_READY_MS = 90000;
+// The public IPFS API: an IPFS_ENDPOINT naming it is not an endpoint of the
+// application's own, so the publish runs its own Kubo instead.
+const PUBLIC_IPFS_HOST = 'ipfs.ethernity.cloud';
+
+const PRIVATE = /^\/ip4\/(127\.|10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.|0\.0\.0\.0|169\.254\.)|^\/ip6\/(::1|fe80|fc|fd)/;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function portFree(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.listen(port, '0.0.0.0', () => server.close(() => resolve(true)));
+    });
+}
+
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+    });
+}
+
+// Whether the configured endpoint is one of the application's own; the public
+// API and an empty setting both mean "run a Kubo for this publish".
+function ownEndpoint(endpoint) {
+    if (!endpoint) return false;
+    try {
+        return new URL(endpoint).hostname !== PUBLIC_IPFS_HOST;
+    } catch (e) {
+        return false;
+    }
+}
+
+class LocalKubo {
+    constructor(name) {
+        this.container = `ecld-kubo-${String(name || 'publish').replace(/[^A-Za-z0-9_.-]/g, '-')}`;
+        this.peers = (process.env.ECLD_IPFS_PEERS || BOOTNODE_MULTIADDR).split(',').map((p) => p.trim()).filter(Boolean);
+        this.apiUrl = null;
+    }
+
+    async api(command, params, timeout) {
+        const response = await axios.post(`${this.apiUrl}/api/v0/${command}`, null, { params, timeout: timeout || 30000 });
+        return response.data;
+    }
+
+    // Start the container and wait for its API; peer it with the bootnode.
+    // Throws when docker cannot run it or the API does not come up in time.
+    async start() {
+        const apiPort = await freePort();
+        this.apiUrl = `http://127.0.0.1:${apiPort}`;
+        try { execFileSync('docker', ['rm', '-f', this.container], { stdio: 'ignore' }); } catch (e) { /* not running */ }
+        const args = ['run', '-d', '--name', this.container, '-p', `127.0.0.1:${apiPort}:5001`];
+        if (await portFree(SWARM_PORT)) {
+            args.push('-p', `${SWARM_PORT}:4001`, '-p', `${SWARM_PORT}:4001/udp`);
+        }
+        args.push(KUBO_IMAGE, 'daemon', '--init', '--migrate=true');
+        try {
+            execFileSync('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        } catch (e) {
+            throw new Error(`docker could not start ${KUBO_IMAGE}: ${String(e.stderr || e.message).trim()}`);
+        }
+        const deadline = Date.now() + API_READY_MS;
+        for (;;) {
+            try {
+                await this.api('id', {}, 5000);
+                break;
+            } catch (e) {
+                if (Date.now() > deadline) {
+                    this.stop();
+                    throw new Error(`the Kubo API did not come up in ${API_READY_MS / 1000}s`);
+                }
+                await sleep(2000);
+            }
+        }
+        // The peering service dials each peer and keeps the connection; the
+        // connect is waited for, not forced, since the service's own dial and
+        // a swarm/connect of the same peer refuse each other.
+        for (const peer of this.peers) {
+            try {
+                await this.api('swarm/peering/add', { arg: peer }, 15000);
+            } catch (e) {
+                console.log(`\t⚠  could not peer with ${peer}: ${e.message}`);
+                continue;
+            }
+            const until = Date.now() + 30000;
+            while (!(await this.connectedTo(peer)) && Date.now() < until) {
+                await sleep(1000);
+            }
+            if (!(await this.connectedTo(peer))) {
+                console.log(`\t⚠  not connected to ${peer} yet; the peering service keeps trying`);
+            }
+        }
+    }
+
+    // How this Kubo is registered on chain: its first public address with the
+    // peer id, or /p2p/<id> when it has none a stranger could dial (the
+    // bootnode reaches it over the connection it opened).
+    async peerMultiaddr() {
+        const identity = await this.api('id', {});
+        const peerId = identity.ID;
+        for (const address of identity.Addresses || []) {
+            if (!PRIVATE.test(address) && !address.includes('/p2p-circuit') && address.includes(`/p2p/${peerId}`)) {
+                return address;
+            }
+        }
+        return `/p2p/${peerId}`;
+    }
+
+    // Announce `cid` to the DHT so a node not connected to this one can find
+    // it. Best effort.
+    async provide(cid) {
+        try {
+            await axios.post(`${this.apiUrl}/api/v0/routing/provide`, null, { params: { arg: cid }, timeout: 180000 });
+        } catch (e) {
+            console.log(`\t⚠  could not announce ${cid}: ${e.message}`);
+        }
+    }
+
+    async connectedTo(peerMultiaddr) {
+        const peerId = peerMultiaddr.split('/p2p/').pop();
+        try {
+            const peers = (await this.api('swarm/peers', {})).Peers || [];
+            return peers.some((p) => p.Peer === peerId);
+        } catch (e) {
+            return false;
+        }
+    }
+
+    stop() {
+        try { execFileSync('docker', ['rm', '-f', this.container], { stdio: 'ignore' }); } catch (e) { /* already gone */ }
+    }
+}
+
+module.exports = { LocalKubo, ownEndpoint, PUBLIC_IPFS_HOST };