@ethernity-cloud/sdk-js 1.5.5 → 1.5.9

package/info.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * ecld-info: everything a developer needs to read or troubleshoot an enclave.
+ *
+ * Read-only and free (eth_call + event logs -- no task, no gas, no private
+ * key). Reads your project's identity from .env (PROJECT_NAME / IPFS_HASH /
+ * BLOCKCHAIN_NETWORK), then reports:
+ *
+ *   NETWORK       name, type, chain id, RPC, contract addresses, live block
+ *   TRUSTEDZONE   the gatekeeper enclave's Image Registry record
+ *   SECURELOCK    the executor enclave's Image Registry record
+ *   ESR           registry address, total keys, and -- with --enclave <wallet>
+ *                 -- this enclave's recent StateCommitted events
+ *
+ * Subcommands (default: the full summary):
+ *   ecld-info                       full summary
+ *   ecld-info network               just the network section
+ *   ecld-info trustedzone           just the trustedzone registration
+ *   ecld-info securelock            just the securelock registration
+ *   ecld-info esr address|count|state|version|list   ESR inspection
+ *
+ * Registration is keyed by the image's IPFS hash: pass --ipfs <hash> for an
+ * exact record, or --name <n> to resolve the latest registered version of a
+ * name. With neither, .env IPFS_HASH / PROJECT_NAME are used.
+ *
+ * Network: --network NAME, else ESR_NETWORK env, else .env BLOCKCHAIN_NETWORK,
+ * else BLOXBERG_TESTNET.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { ethers } = require('ethers');
+try { require('dotenv').config(); } catch (e) { /* dotenv optional */ }
+
+// Authoritative per-network values (mirror of the Python SDK's network table).
+const NETWORKS = {
+  BLOXBERG_MAINNET: {
+    type: 'mainnet', chainId: 8995, rpc: 'https://core.bloxberg.org',
+    protocol: '0x549A6E06BB2084100148D50F51CF77a3436C3Ae7',
+    imageRegistry: '0x15D73a742529C3fb11f3FA32EF7f0CC3870ACA31',
+    esr: '0xF76469A5659670B6ade366dE635e6463aaB8f3D8',
+  },
+  BLOXBERG_TESTNET: {
+    type: 'testnet', chainId: 8995, rpc: 'https://core.bloxberg.org',
+    protocol: '0x02882F03097fE8cD31afbdFbB5D72a498B41112c',
+    imageRegistry: '0x15D73a742529C3fb11f3FA32EF7f0CC3870ACA31',
+    esr: '0xda5e68Bb5e68ee14D73b8de2a4D3Ca15736fACfb',
+  },
+  LITVM_LITEFORGE: {
+    type: 'testnet', chainId: 0, rpc: 'https://liteforge.rpc.caldera.xyz/infra-partner-http',
+    protocol: '', imageRegistry: '', esr: '0xbAa7F9E3287ff95D177104eD469E6d0Fd19dBB0F',
+  },
+};
+
+const IMAGE_REGISTRY_ABI = [
+  'function imageDetails(string) view returns (address owner, string ipfsHash, string version, string session, uint256 fee, address rewardAddress, bool validated, bool published, string certPublicKey, string dockerComposeHash, string name)',
+  'function trustedZoneImageDetails(string) view returns (address owner, string ipfsHash, string version, string session, uint256 fee, address rewardAddress, bool validated, bool published, string certPublicKey, string dockerComposeHash, string name)',
+  'function imageVersions(string, uint256) view returns (string)',
+  'function trustedZoneImageVersions(string, uint256) view returns (string)',
+];
+
+const ESR_ABI = [
+  'function getState(address enclave, bytes32 key) view returns (string cid, uint256 version, uint64 updatedAt)',
+  'function getVersion(address enclave, bytes32 key) view returns (uint256)',
+  'function exists(address enclave, bytes32 key) view returns (bool)',
+  'function entryCount() view returns (uint256)',
+  'function getEntriesFrom(uint256 start, uint256 limit) view returns (address[] enclaves, bytes32[] keys, string[] cids, uint256[] versions, uint64[] updatedAts, uint256 total)',
+  'event StateCommitted(address indexed enclave, bytes32 indexed key, string cid, uint256 version, uint256 seq)',
+];
+
+function resolveNetwork(name) {
+  name = (name || process.env.ESR_NETWORK || process.env.BLOCKCHAIN_NETWORK || 'BLOXBERG_TESTNET')
+    .toUpperCase();
+  const net = NETWORKS[name];
+  if (!net) {
+    throw new Error(`Unknown network '${name}'. Known: ${Object.keys(NETWORKS).join(', ')}`);
+  }
+  return { name, net };
+}
+
+function provider(rpc) {
+  return new ethers.providers.JsonRpcProvider(rpc);
+}
+
+function keyHash(key) {
+  return ethers.utils.id(key); // keccak256(utf8(key))
+}
+
+function looksLikeCID(cid) {
+  return typeof cid === 'string' && (cid.startsWith('Qm') || cid.startsWith('bafk')) && cid.length > 20;
+}
+
+function decodeDetails(d, fallbackName) {
+  return {
+    name: d.name || fallbackName,
+    published: Boolean(d.published),
+    validated: Boolean(d.validated),
+    image_ipfs_hash: d.ipfsHash || null,
+    image_version: d.version || null,
+    reward_address: d.rewardAddress,
+    owner: d.owner,
+    docker_compose_hash: d.dockerComposeHash || null,
+    attestation_session: Boolean(d.session),
+    cert_present: Boolean(d.certPublicKey),
+  };
+}
+
+async function lookupRegistration(reg, kind, ipfs, name) {
+  const detailsFn = kind === 'trustedzone' ? 'trustedZoneImageDetails' : 'imageDetails';
+  const versionsFn = kind === 'trustedzone' ? 'trustedZoneImageVersions' : 'imageVersions';
+  if (ipfs) {
+    try { return decodeDetails(await reg[detailsFn](ipfs), ipfs); }
+    catch (e) { return { found: false, error: e.message }; }
+  }
+  if (name) {
+    let latest = null;
+    for (let i = 0; i < 64; i += 1) {
+      let v;
+      try { v = await reg[versionsFn](name, i); } catch (e) { break; }
+      if (!v) break;
+      latest = v;
+    }
+    if (latest) {
+      try { return decodeDetails(await reg[detailsFn](latest), name); }
+      catch (e) { return { found: false, error: e.message }; }
+    }
+    return { found: false, note: `no registered version for name '${name}' -- the Image Registry is keyed by image IPFS hash; pass --ipfs <hash>` };
+  }
+  return { found: false, note: 'no --ipfs or --name to look up' };
+}
+
+async function sectionNetwork(prov, name, net) {
+  const out = {
+    network: name, type: net.type, chain_id: net.chainId, rpc: net.rpc,
+    protocol_contract: net.protocol || '(n/a)',
+    image_registry: net.imageRegistry || '(n/a)',
+    esr_contract: net.esr || '(not deployed)',
+  };
+  try {
+    out.latest_block = await prov.getBlockNumber();
+    out.connected = true;
+  } catch (e) {
+    out.connected = false; out.error = e.message;
+  }
+  return out;
+}
+
+async function sectionRegistration(prov, net, kind, ipfs, name) {
+  if (!net.imageRegistry) return { note: 'no image registry on this network' };
+  const reg = new ethers.Contract(net.imageRegistry, IMAGE_REGISTRY_ABI, prov);
+  return lookupRegistration(reg, kind, ipfs, name);
+}
+
+async function sectionEsr(prov, net, enclaveWallet, eventsN) {
+  if (!net.esr) return { note: 'ESR is not deployed on this network' };
+  const esr = new ethers.Contract(net.esr, ESR_ABI, prov);
+  const out = { esr_contract: net.esr };
+  try { out.total_registry_entries = (await esr.entryCount()).toNumber(); } catch (e) { /* ignore */ }
+  if (enclaveWallet) {
+    try {
+      const latest = await prov.getBlockNumber();
+      const from = Math.max(0, latest - 500000);
+      const flt = esr.filters.StateCommitted(ethers.utils.getAddress(enclaveWallet));
+      let logs = await esr.queryFilter(flt, from, 'latest');
+      logs = logs.slice(-eventsN);
+      out.recent_commits = logs.map((l) => ({
+        key_hash: l.args.key,
+        version: l.args.version.toNumber(),
+        cid: l.args.cid,
+        seq: l.args.seq.toNumber(),
+        block: l.blockNumber,
+      }));
+    } catch (e) {
+      out.recent_commits_error = e.message;
+    }
+  } else {
+    out.recent_commits_note = 'pass --enclave <ESR wallet> to list this enclave\'s state commits';
+  }
+  return out;
+}
+
+async function esrQuery(prov, name, net, args) {
+  const esrAddr = args.contract || net.esr;
+  const sub = args.esrCmd || 'address';
+  if (sub === 'address') return { network: name, esr_contract: esrAddr || '(not deployed)', rpc: net.rpc };
+  if (!esrAddr) throw new Error(`ESR is not deployed on ${name}.`);
+  const c = new ethers.Contract(esrAddr, ESR_ABI, prov);
+  if (sub === 'count') return { network: name, entry_count: (await c.entryCount()).toNumber() };
+  if (sub === 'version') {
+    const v = (await c.getVersion(ethers.utils.getAddress(args.enclave), keyHash(args.key))).toNumber();
+    return { enclave: args.enclave, key: args.key, version: v };
+  }
+  if (sub === 'state') {
+    const enclave = ethers.utils.getAddress(args.enclave);
+    const kh = keyHash(args.key);
+    const [cid, version, updated] = await c.getState(enclave, kh);
+    const exists = await c.exists(enclave, kh);
+    return {
+      network: name, enclave: args.enclave, key: args.key, key_hash: kh,
+      exists, version: version.toNumber(), cid: cid || null, cid_valid: looksLikeCID(cid),
+      updated_at: updated.toNumber(),
+      note: 'cid points at ENCRYPTED state; only the enclave can decrypt it',
+    };
+  }
+  if (sub === 'list') {
+    const start = parseInt(args.start || 0, 10);
+    const limit = parseInt(args.limit || 50, 10);
+    const [encs, keys, cids, versions, updated, total] = await c.getEntriesFrom(start, limit);
+    const entries = encs.map((e, i) => ({
+      enclave: e, key_hash: keys[i], cid: cids[i] || null,
+      version: versions[i].toNumber(), updated_at: updated[i].toNumber(),
+    }));
+    return { network: name, total: total.toNumber(), start, returned: entries.length, entries };
+  }
+  throw new Error(`unknown esr subcommand: ${sub}`);
+}
+
+// ---- arg parsing (tiny, dependency-free) -----------------------------------
+
+function parseArgs(argv) {
+  const a = { _: [], json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const t = argv[i];
+    if (t === '--json') a.json = true;
+    else if (t.startsWith('--')) { a[t.slice(2)] = argv[i + 1]; i += 1; }
+    else a._.push(t);
+  }
+  return a;
+}
+
+function emit(obj, asJson) {
+  if (asJson) { console.log(JSON.stringify(obj, null, 2)); return; }
+  for (const [k, v] of Object.entries(obj)) {
+    if (Array.isArray(v)) { console.log(`${k}:`); v.forEach((it) => console.log('  ' + JSON.stringify(it))); }
+    else console.log(`${k}: ${v}`);
+  }
+}
+
+function printFull(info) {
+  const n = info.network;
+  console.log('NETWORK');
+  console.log(`  ${n.network} (${n.type}, chain ${n.chain_id})   block ${n.latest_block || '?'}   ${n.connected ? 'connected' : 'NOT CONNECTED'}`);
+  console.log(`  rpc:            ${n.rpc}`);
+  console.log(`  protocol:       ${n.protocol_contract}`);
+  console.log(`  image registry: ${n.image_registry}`);
+  console.log(`  esr:            ${n.esr_contract}`);
+  for (const [label, key] of [['TRUSTEDZONE', 'trustedzone'], ['SECURELOCK', 'securelock']]) {
+    const r = info[key] || {};
+    console.log(label);
+    if (r.published || r.validated || r.image_ipfs_hash) {
+      console.log(`  published:    ${r.published ? 'yes' : 'no'}   validated: ${r.validated ? 'yes' : 'no'}`);
+      console.log(`  image hash:   ${r.image_ipfs_hash}`);
+      console.log(`  version:      ${r.image_version}`);
+      console.log(`  reward addr:  ${r.reward_address}`);
+      console.log(`  attestation:  ${r.attestation_session ? 'MRENCLAVE session present' : 'none'}`);
+    } else {
+      console.log(`  not found     (${r.error || r.note || 'not registered'})`);
+    }
+  }
+  const e = info.esr || {};
+  console.log('ESR');
+  if (e.note) { console.log(`  ${e.note}`); return; }
+  console.log(`  registry:     ${e.esr_contract}`);
+  if ('total_registry_entries' in e) console.log(`  total keys:   ${e.total_registry_entries} (all enclaves)`);
+  if (e.recent_commits) {
+    console.log(`  recent state commits for this enclave: ${e.recent_commits.length}`);
+    e.recent_commits.forEach((c) => console.log(`    v${c.version}  seq ${c.seq}  ${c.key_hash}  ${c.cid}  (block ${c.block})`));
+  } else if (e.recent_commits_note) console.log(`  ${e.recent_commits_note}`);
+  else if (e.recent_commits_error) console.log(`  (could not read commits: ${e.recent_commits_error})`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const section = args._[0];               // network | trustedzone | securelock | esr | undefined
+  const { name: netName, net } = resolveNetwork(args.network);
+  const prov = provider(net.rpc);
+
+  const ipfs = args.ipfs || process.env.IPFS_HASH || null;
+  const projName = args.name || process.env.PROJECT_NAME || null;
+
+  if (section === 'esr') {
+    args.esrCmd = args._[1];
+    const obj = await esrQuery(prov, netName, net, args);
+    emit(obj, args.json);
+    return;
+  }
+  if (section === 'network') { emit(await sectionNetwork(prov, netName, net), args.json); return; }
+  if (section === 'trustedzone') { emit(await sectionRegistration(prov, net, 'trustedzone', ipfs, projName), args.json); return; }
+  if (section === 'securelock') { emit(await sectionRegistration(prov, net, 'securelock', ipfs, projName), args.json); return; }
+
+  const info = {
+    project: { name: projName || '(unknown)', dapp_type: process.env.SERVICE_TYPE || process.env.DAPP_TYPE, version: process.env.VERSION },
+    network: await sectionNetwork(prov, netName, net),
+    trustedzone: await sectionRegistration(prov, net, 'trustedzone', ipfs, projName),
+    securelock: await sectionRegistration(prov, net, 'securelock', ipfs, projName),
+    esr: await sectionEsr(prov, net, args.enclave || null, parseInt(args.events || 10, 10)),
+  };
+  if (args.json) { console.log(JSON.stringify(info, null, 2)); return; }
+  const pr = info.project;
+  console.log(`PROJECT  ${pr.name}${pr.dapp_type ? '   type ' + pr.dapp_type : ''}${pr.version != null ? '   version ' + pr.version : ''}`);
+  printFull(info);
+}
+
+main().catch((e) => { console.error(`ecld-info: ${e.message}`); process.exit(1); });

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

@@ -54,7 +54,7 @@ let _provider = null;
  * Wire the registry to the enclave's identity, storage and chain access.
  * Called by securelock at task start; payload code never calls this.
  */
-function configure({ identityPriv, swiftStreamService, bucket, contractAddress, provider }) {
+function configure({ identityPriv, swiftStreamService, bucket, contractAddress, provider, caller = null }) {
   _identityPriv = identityPriv;
   _swift = swiftStreamService;
   _bucket = bucket;
@@ -62,6 +62,104 @@ function configure({ identityPriv, swiftStreamService, bucket, contractAddress,
   _provider = provider;
   _esrLedger = [];
   _taskLedger = {};
+  _taskCaller = normAddr(caller);
+}
+
+// The authenticated task caller: the wallet that placed the DO request, read
+// from the PoX contract by the TRUSTEDZONE and forwarded over its signed
+// handoff (caller.securelock + .sig, verified by securelock before configure).
+// null when the trustedzone did not supply one -- anonymity is never a
+// privilege: null cannot claim ownership or touch owned state.
+let _taskCaller = null;
+
+function taskCaller() {
+  return _taskCaller;
+}
+
+function normAddr(addr) {
+  return typeof addr === 'string' && addr ? addr.toLowerCase() : null;
+}
+
+/**
+ * State container + ACL. Stored blobs are either legacy (raw state --
+ * "unowned") or an owned container:
+ *   { _ecld_state: 1, acl: {...}, data: <state> }
+ * acl = { owner, read: [], write: [], public_read: false }. Enforcement
+ * happens HERE, inside the enclave, against the trustedzone-attested caller.
+ */
+const CONTAINER_MARK = '_ecld_state';
+
+class StatePermissionError extends Error {}
+
+function unwrapStored(stored) {
+  if (stored && typeof stored === 'object' && stored[CONTAINER_MARK] === 1) {
+    return [stored.acl || null, stored.data];
+  }
+  return [null, stored];
+}
+
+function wrapStored(acl, data, committedBy = 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 };
+  if (committedBy) container.committedBy = committedBy;
+  return container;
+}
+
+/**
+ * Post-payload: re-assert the trusted caller across the ESR ledger. Called by
+ * the securelock after the payload returns, with the attested caller captured
+ * before execution (outside the payload's reach). Overwrites callerUsed (and
+ * re-fixes enclave to the real signer) in every owned entry and RE-STAGES the
+ * ledger, so a forged callerUsed cannot reach the trustedzone. Returns true if
+ * any entry's callerUsed differed from the trusted value (tamper detected).
+ * Defence in depth -- the trustedzone and the CID-bound caller are the sound
+ * layers; this runs in the same process the payload subverted.
+ */
+async function restampLedgerCaller(trustedCaller) {
+  const trusted = normAddr(trustedCaller);
+  if (!_esrLedger.length) return false;
+  let tampered = false;
+  let signerAddr = null;
+  try {
+    signerAddr = await new StateRegistry()._signer().getAddress();
+  } catch (e) { signerAddr = null; }
+  for (const entry of _esrLedger) {
+    if (!entry.owned) continue;
+    if (normAddr(entry.callerUsed) !== trusted) tampered = true;
+    entry.callerUsed = trusted || '';
+    if (signerAddr) entry.enclave = signerAddr;
+  }
+  try {
+    await _swift.putFileContent(
+      _bucket, 'esr.authorizations.json', '',
+      Buffer.from(JSON.stringify(_esrLedger), 'utf8'));
+  } catch (e) { /* best-effort restage; trustedzone still adjudicates */ }
+  return tampered;
+}
+
+function aclMembers(acl, field) {
+  return new Set((acl[field] || []).map(normAddr).filter(Boolean));
+}
+
+function canRead(acl) {
+  if (!acl || acl.public_read) return true;
+  const c = _taskCaller;
+  if (!c) return false;
+  return c === normAddr(acl.owner) || aclMembers(acl, 'read').has(c) || aclMembers(acl, 'write').has(c);
+}
+
+function canWrite(acl) {
+  if (!acl) return true;                 // unowned: writable; claimed when a caller exists
+  const c = _taskCaller;
+  if (!c) return false;
+  return c === normAddr(acl.owner) || aclMembers(acl, 'write').has(c);
+}
+
+function newAcl(owner) {
+  return { owner, read: [], write: [], public_read: false };
 }
 
 // Task-scoped ledger of every state key this execution touched, recorded by
@@ -247,10 +345,22 @@ class StateRegistry {
    * state" would let the next commit overwrite data that is still recoverable.
    */
   async get(key, fallback = {}) {
+    const [acl, data, version, cid] = await this._readContainer(key, fallback);
+    if (!canRead(acl)) {
+      throw new StatePermissionError(
+        `caller ${_taskCaller || '<anonymous>'} has no read permission on ` +
+          `state key '${key}' (owner: ${acl.owner})`
+      );
+    }
+    ledgerRecord(key, version || 0, cid, data);
+    return data;
+  }
+
+  /** [acl, data, version, cid] for `key`; NO permission check here. */
+  async _readContainer(key, fallback = {}) {
     const [cid, version] = await this._contract().getState(this.walletAddress, keyHash(key));
     if (!version || !cid) {
-      ledgerRecord(key, 0, null, fallback);
-      return fallback;
+      return [null, fallback, 0, null];
     }
     if (!looksLikeCID(cid)) {
       throw new Error(
@@ -259,9 +369,9 @@ class StateRegistry {
       );
     }
     const blob = await this._fetch(key, cid);
-    const state = JSON.parse(decrypt(blob).toString('utf8'));
-    ledgerRecord(key, version, cid, state);
-    return state;
+    const stored = JSON.parse(decrypt(blob).toString('utf8'));
+    const [acl, data] = unwrapStored(stored);
+    return [acl, data, Number(version), cid];
   }
 
   /**
@@ -272,15 +382,39 @@ class StateRegistry {
    * retry, so concurrent tasks cannot silently lose updates.
    */
   async commit(key, mutate, attempts = 3) {
+    const transform = async (acl, data) => {
+      if (!canWrite(acl)) {
+        throw new StatePermissionError(
+          `caller ${_taskCaller || '<anonymous>'} has no write permission on ` +
+            `state key '${key}' (owner: ${acl.owner})`
+        );
+      }
+      let nextAcl = acl;
+      if (!nextAcl && _taskCaller) nextAcl = newAcl(_taskCaller); // first-writer-owns
+      return [nextAcl, await mutate(data)];
+    };
+    const [, newData] = await this._commitTransform(key, transform, attempts);
+    return newData;
+  }
+
+  /**
+   * Optimistic-concurrency commit of transform(acl, data, version) ->
+   * [newAcl, newData]. The stored blob is the wrapped container (or the bare
+   * 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) {
     let lastError = null;
     for (let attempt = 0; attempt < attempts; attempt += 1) {
       // eslint-disable-next-line no-await-in-loop
-      const currentVersion = await this.getVersion(key);
+      const [acl, data, currentVersion] = await this._readContainer(key);
       // eslint-disable-next-line no-await-in-loop
-      const current = currentVersion ? await this.get(key) : {};
-      const newState = await mutate(current);
+      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 blob = encrypt(Buffer.from(JSON.stringify(newState), 'utf8'));
+      const blob = encrypt(Buffer.from(JSON.stringify(stored), 'utf8'));
       // Compute the CID from OUR bytes — never accept one from the node.
       const cid = cidv1Raw(blob);
 
@@ -291,11 +425,12 @@ class StateRegistry {
 
       try {
         // eslint-disable-next-line no-await-in-loop
-        await this._sendCommit(keyHash(key), cid, currentVersion);
-        // Record the POST-commit values: this is what the chain will show
-        // once the node's relay lands (version increments by one).
-        ledgerRecord(key, currentVersion + 1, cid, newState);
-        return newState;
+        await this._sendCommit(keyHash(key), cid, currentVersion,
+          nextAcl ? normAddr(nextAcl.owner) : null);
+        // Record the POST-commit values (the DATA -- the ACL never leaves in
+        // results): this is what the chain shows once the relay lands.
+        ledgerRecord(key, currentVersion + 1, cid, newData);
+        return [nextAcl, newData];
       } catch (e) {
         const msg = String(e && e.message ? e.message : e);
         if (/VersionMismatch/i.test(msg) || /version/i.test(msg)) {
@@ -339,7 +474,7 @@ class StateRegistry {
     throw new Error(`Could not read state object for '${key}' (${cid})`);
   }
 
-  async _sendCommit(keyHashHex, cid, expectedVersion) {
+  async _sendCommit(keyHashHex, cid, expectedVersion, ownerAddr = null) {
     // The enclave never pays gas and does NO gas math: it SIGNS the commit
     // (commitFor) and stages the signed authorization for the node, which
     // relays it and pays. The trustedzone independently re-prices the whole
@@ -362,7 +497,15 @@ class StateRegistry {
       cid,
       expectedVersion: Number(expectedVersion),
       relayNonce: Number(relayNonce),
-      signature
+      signature,
+      // IMPERSONATION GUARD: the trustedzone requires callerUsed to equal the
+      // DO owner it reads from the PoX contract, so a payload that forged the
+      // in-enclave caller to impersonate another user is rejected outside the
+      // payload's process. It does NOT verify the caller was a permitted
+      // writer (it cannot read the encrypted ACL). Unowned commits carry no
+      // constraint.
+      callerUsed: _taskCaller || '',
+      owned: Boolean(ownerAddr)
     };
 
     _esrLedger.push(auth);
@@ -376,10 +519,100 @@ class StateRegistry {
   }
 }
 
+/** Owner-only ACL mutation; an unowned key is claimed first (owner = caller). */
+async function ownerOp(key, mutator) {
+  if (!_taskCaller) {
+    throw new StatePermissionError(
+      'state management requires an authenticated caller (the trustedzone supplied none)'
+    );
+  }
+  const reg = new StateRegistry();
+  const transform = async (acl, data) => {
+    let nextAcl = acl || newAcl(_taskCaller);
+    if (normAddr(nextAcl.owner) !== _taskCaller) {
+      throw new StatePermissionError(
+        `caller ${_taskCaller} is not the owner of state key '${key}' (owner: ${nextAcl.owner})`
+      );
+    }
+    nextAcl = mutator({ ...nextAcl });
+    return [nextAcl, data];
+  };
+  const [acl] = await reg._commitTransform(key, transform);
+  return { ...acl };
+}
+
+function assertLevel(level) {
+  if (level !== 'read' && level !== 'write') throw new Error("level must be 'read' or 'write'");
+}
+
+async function esrGrant(key, address, level = 'read') {
+  assertLevel(level);
+  const addr = normAddr(address);
+  if (!addr) throw new Error('a grantee address is required');
+  return ownerOp(key, (acl) => {
+    const members = new Set((acl[level] || []).map(normAddr).filter(Boolean));
+    members.add(addr);
+    acl[level] = [...members].sort();
+    return acl;
+  });
+}
+
+async function esrRevoke(key, address, level = 'read') {
+  assertLevel(level);
+  const addr = normAddr(address);
+  return ownerOp(key, (acl) => {
+    acl[level] = (acl[level] || []).map(normAddr).filter((a) => a && a !== addr).sort();
+    return acl;
+  });
+}
+
+async function esrSetPublicRead(key, enabled = true) {
+  return ownerOp(key, (acl) => {
+    acl.public_read = Boolean(enabled);
+    return acl;
+  });
+}
+
+async function esrTransfer(key, newOwner) {
+  const addr = normAddr(newOwner);
+  if (!addr) throw new Error('a new owner address is required');
+  return ownerOp(key, (acl) => {
+    acl.owner = addr;
+    return acl;
+  });
+}
+
+/** Owner address of `key`, or null while unowned. Exposes nothing else. */
+async function esrOwner(key) {
+  const [acl] = await new StateRegistry()._readContainer(key);
+  return acl ? acl.owner : null;
+}
+
+/** Owner-only: the full ACL of `key`. */
+async function esrAcl(key) {
+  const [acl] = await new StateRegistry()._readContainer(key);
+  if (!acl) return null;
+  if (!_taskCaller || normAddr(acl.owner) !== _taskCaller) {
+    throw new StatePermissionError(
+      `caller ${_taskCaller || '<anonymous>'} is not the owner of state key '${key}'`
+    );
+  }
+  return { ...acl };
+}
+
 module.exports = {
   StateRegistry,
   configure,
   cidv1Raw,
   looksLikeCID,
-  ledgerSnapshot
+  ledgerSnapshot,
+  taskCaller,
+  restampLedgerCaller,
+  StatePermissionError,
+  esrGrant,
+  esrRevoke,
+  esrSetPublicRead,
+  esrTransfer,
+  esrOwner,
+  esrAcl
 };