@ethernity-cloud/sdk-js 1.6.2 → 1.7.1

package/pynithy/build/securelock/src/esr.abi

@@ -0,0 +1 @@
+[{"inputs": [], "name": "BadSignature", "type": "error"}, {"inputs": [], "name": "EmptyCID", "type": "error"}, {"inputs": [{"internalType": "uint256", "name": "stored", "type": "uint256"}, {"internalType": "uint256", "name": "given", "type": "uint256"}], "name": "NonceOutOfOrder", "type": "error"}, {"inputs": [{"internalType": "uint256", "name": "expected", "type": "uint256"}, {"internalType": "uint256", "name": "actual", "type": "uint256"}], "name": "RelayNonceMismatch", "type": "error"}, {"inputs": [{"internalType": "uint256", "name": "expected", "type": "uint256"}, {"internalType": "uint256", "name": "actual", "type": "uint256"}], "name": "VersionMismatch", "type": "error"}, {"anonymous": false, "inputs": [{"indexed": true, "internalType": "address", "name": "enclave", "type": "address"}, {"indexed": true, "internalType": "bytes32", "name": "key", "type": "bytes32"}, {"indexed": false, "internalType": "string", "name": "cid", "type": "string"}, {"indexed": false, "internalType": "uint256", "name": "version", "type": "uint256"}, {"indexed": false, "internalType": "uint256", "name": "seq", "type": "uint256"}, {"indexed": false, "internalType": "uint256", "name": "nonce", "type": "uint256"}], "name": "StateCommitted", "type": "event"}, {"inputs": [{"internalType": "bytes32", "name": "key", "type": "bytes32"}, {"internalType": "string", "name": "newCID", "type": "string"}, {"internalType": "uint256", "name": "expectedVersion", "type": "uint256"}, {"internalType": "uint256", "name": "nonce", "type": "uint256"}], "name": "commit", "outputs": [], "stateMutability": "nonpayable", "type": "function"}, {"inputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}, {"internalType": "string", "name": "newCID", "type": "string"}, {"internalType": "uint256", "name": "expectedVersion", "type": "uint256"}, {"internalType": "uint256", "name": "relayNonce", "type": "uint256"}, {"internalType": "uint256", "name": "nonce", "type": "uint256"}], "name": "commitDigest", "outputs": [{"internalType": "bytes32", "name": "", "type": "bytes32"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}, {"internalType": "string", "name": "newCID", "type": "string"}, {"internalType": "uint256", "name": "expectedVersion", "type": "uint256"}, {"internalType": "uint256", "name": "relayNonce", "type": "uint256"}, {"internalType": "uint256", "name": "nonce", "type": "uint256"}, {"internalType": "bytes", "name": "signature", "type": "bytes"}], "name": "commitFor", "outputs": [], "stateMutability": "nonpayable", "type": "function"}, {"inputs": [], "name": "commitSeq", "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "uint256", "name": "index", "type": "uint256"}], "name": "entryAt", "outputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}], "stateMutability": "view", "type": "function"}, {"inputs": [], "name": "entryCount", "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}], "name": "exists", "outputs": [{"internalType": "bool", "name": "", "type": "bool"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "uint256", "name": "startIndex", "type": "uint256"}, {"internalType": "uint256", "name": "limit", "type": "uint256"}], "name": "getEntriesFrom", "outputs": [{"internalType": "address[]", "name": "enclaves", "type": "address[]"}, {"internalType": "bytes32[]", "name": "keys", "type": "bytes32[]"}, {"internalType": "string[]", "name": "cids", "type": "string[]"}, {"internalType": "uint256[]", "name": "versions", "type": "uint256[]"}, {"internalType": "uint64[]", "name": "updatedAts", "type": "uint64[]"}, {"internalType": "uint256", "name": "total", "type": "uint256"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}], "name": "getNonce", "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}], "name": "getState", "outputs": [{"internalType": "string", "name": "cid", "type": "string"}, {"internalType": "uint256", "name": "version", "type": "uint256"}, {"internalType": "uint64", "name": "updatedAt", "type": "uint64"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}], "name": "getVersion", "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"}, {"inputs": [{"internalType": "address", "name": "enclave", "type": "address"}, {"internalType": "bytes32", "name": "key", "type": "bytes32"}], "name": "relayNonce", "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"}]

package/pynithy/build/securelock/src/esr_local.py

@@ -0,0 +1,267 @@
+"""Local ESR emulator for `ecld-test` -- run state-using backends with no chain.
+
+Provides in-memory stand-ins for the two external dependencies StateRegistry
+talks to, so `get`/`commit`/`esr_grant`/... behave EXACTLY as on-chain but
+in-process and instantly, with zero orders and zero gas:
+
+  * MemSwift    -- the state-blob store (replaces the SwiftStream service):
+                   put_file_content / get_file_content_bytes over a dict,
+                   optionally mirrored to a JSON file so state survives across
+                   `ecld-test` runs (the counter keeps counting).
+  * MemRegistry -- the ESR contract (getState / getVersion / relayNonce /
+                   commitDigest, and the commit APPLY that the node would do
+                   on-chain), keyed by (enclave, keccak(key)) -> (cid, version).
+
+`install(ecld_state, caller=..., file=...)` wires these into the ecld_state
+module and sets the local commit-apply hook, so no chain, node, or SGX is
+needed. Used only by the local test API; the real enclave never imports this.
+"""
+
+import base64
+import json
+import os
+
+
+# ---- storage ---------------------------------------------------------------
+
+class MemSwift:
+    """SwiftStream stand-in: (bucket, object) -> bytes, over a dict.
+
+    Mirrors to `file` (base64 JSON) when given, so committed state persists
+    across separate `ecld-test` invocations.
+    """
+
+    def __init__(self, file=None):
+        self._file = file
+        self._store = {}
+        if file and os.path.exists(file):
+            try:
+                with open(file, encoding="utf-8") as f:
+                    raw = json.load(f)
+                self._store = {k: base64.b64decode(v) for k, v in raw.items()}
+            except Exception:
+                self._store = {}
+
+    def _persist(self):
+        if not self._file:
+            return
+        try:
+            enc = {k: base64.b64encode(v).decode("ascii") for k, v in self._store.items()}
+            tmp = self._file + ".tmp"
+            with open(tmp, "w", encoding="utf-8") as f:
+                json.dump(enc, f)
+            os.replace(tmp, self._file)
+        except Exception:
+            pass
+
+    def put_file_content(self, bucket, object_name, _prefix, io_obj):
+        data = io_obj.getvalue() if hasattr(io_obj, "getvalue") else bytes(io_obj)
+        self._store["%s/%s" % (bucket, object_name)] = data
+        self._persist()
+        return True, None
+
+    def get_file_content_bytes(self, bucket, object_name):
+        data = self._store.get("%s/%s" % (bucket, object_name))
+        if data is None:
+            return False, None
+        return True, data
+
+    # Some code paths use the string variant; provide it too.
+    def get_file_content(self, bucket, object_name):
+        ok, data = self.get_file_content_bytes(bucket, object_name)
+        return (ok, data.decode("utf-8") if ok else None)
+
+    def create_bucket(self, *a, **k):
+        return True
+
+
+# ---- registry --------------------------------------------------------------
+
+class _Callable:
+    """A web3-style bound function: .call() returns the precomputed value."""
+
+    def __init__(self, value):
+        self._value = value
+
+    def call(self, *a, **k):
+        return self._value
+
+
+class _Functions:
+    def __init__(self, reg):
+        self._reg = reg
+
+    def getState(self, enclave, key_hash):
+        cid, version, updated = self._reg.state(enclave, key_hash)
+        return _Callable([cid, version, updated])
+
+    def getVersion(self, enclave, key_hash):
+        _cid, version, _u = self._reg.state(enclave, key_hash)
+        return _Callable(version)
+
+    def relayNonce(self, enclave, key_hash):
+        return _Callable(self._reg.relay_nonce(enclave, key_hash))
+
+    def commitDigest(self, enclave, key_hash, cid, expected_version, relay_nonce,
+                     nonce=0):
+        # Deterministic 32-byte digest over the fields (no real signing needed
+        # locally; the securelock signs it with the local test key). The
+        # idempotency nonce is part of the digest, like on-chain.
+        import hashlib
+        m = hashlib.sha256()
+        m.update(str((enclave, key_hash, cid, expected_version, relay_nonce,
+                      nonce)).encode())
+        return _Callable(m.digest())
+
+    def getNonce(self, enclave, key_hash):
+        return _Callable(self._reg.idem_nonce(enclave, key_hash))
+
+    def entryCount(self):
+        return _Callable(self._reg.entry_count())
+
+
+class _Contract:
+    def __init__(self, reg):
+        self.functions = _Functions(reg)
+
+
+class MemRegistry:
+    """In-memory ESR registry: (enclave, keyHash) -> (cid, version, updatedAt).
+
+    Applies commits directly (the job the node's commitFor does on-chain),
+    enforcing monotonic versions with optimistic concurrency.
+    """
+
+    def __init__(self, file=None):
+        self._file = file
+        # key: "enclave|0xkeyhash" -> {"cid":..., "version":int, "updatedAt":int}
+        self._entries = {}
+        self._nonce = {}
+        if file and os.path.exists(file):
+            try:
+                with open(file, encoding="utf-8") as f:
+                    d = json.load(f)
+                self._entries = d.get("entries", {})
+                self._nonce = d.get("nonce", {})
+            except Exception:
+                pass
+
+    def _persist(self):
+        if not self._file:
+            return
+        try:
+            tmp = self._file + ".tmp"
+            with open(tmp, "w", encoding="utf-8") as f:
+                json.dump({"entries": self._entries, "nonce": self._nonce}, f)
+            os.replace(tmp, self._file)
+        except Exception:
+            pass
+
+    @staticmethod
+    def _k(enclave, key_hash):
+        kh = key_hash.hex() if isinstance(key_hash, (bytes, bytearray)) else str(key_hash)
+        return "%s|%s" % (str(enclave).lower(), kh)
+
+    def state(self, enclave, key_hash):
+        e = self._entries.get(self._k(enclave, key_hash))
+        if not e:
+            return ("", 0, 0)
+        return (e["cid"], int(e["version"]), int(e.get("updatedAt", 0)))
+
+    def idem_nonce(self, enclave, key_hash):
+        """Last accepted idempotency nonce for (enclave, key) -- public data,
+        mirroring the on-chain getNonce view."""
+        e = self._entries.get(self._k(enclave, key_hash))
+        return int(e.get("nonce", 0)) if e else 0
+
+    def relay_nonce(self, enclave, key_hash):
+        # Per (enclave, key), like the contract: same-key commits serialize,
+        # different keys are independent.
+        return int(self._nonce.get(self._k(enclave, key_hash), 0))
+
+    def entry_count(self):
+        return len(self._entries)
+
+    def apply_commit(self, enclave, key_hash, cid, expected_version, nonce=0):
+        """The on-chain commitFor: bump version if expected matches current.
+        Raises 'VersionMismatch' (string in message) on a race, exactly like
+        the contract, so StateRegistry.commit's retry loop behaves the same.
+
+        The per-key nonce advances by EXACTLY 1 on every commit, like the
+        contract: nonce == 0 ("omitted") gets the next value assigned by the
+        registry itself; a non-zero nonce is a client-pinned guard and must
+        be EXACTLY the stored value + 1 (no gaps, no reuse) or
+        'NonceOutOfOrder' is raised."""
+        k = self._k(enclave, key_hash)
+        entry = self._entries.get(k, {})
+        cur = int(entry.get("version", 0))
+        if int(expected_version) != cur:
+            raise RuntimeError("VersionMismatch: expected %s but current is %s"
+                               % (expected_version, cur))
+        stored_nonce = int(entry.get("nonce", 0))
+        n = int(nonce or 0)
+        if n == 0:
+            stored_nonce += 1
+        else:
+            if n != stored_nonce + 1:
+                raise RuntimeError("NonceOutOfOrder: stored %s, given %s"
+                                   % (stored_nonce, n))
+            stored_nonce = n
+        self._entries[k] = {"cid": cid, "version": cur + 1, "updatedAt": 0,
+                            "nonce": stored_nonce}
+        self._nonce[k] = self.relay_nonce(enclave, key_hash) + 1
+        self._persist()
+
+
+# ---- web3 stand-in ---------------------------------------------------------
+
+class MemWeb3:
+    """Just enough of a web3 to satisfy ecld_state._contract()."""
+
+    def __init__(self, reg):
+        self._reg = reg
+
+        class _Eth:
+            def contract(_self, address=None, abi=None):
+                return _Contract(reg)
+        self.eth = _Eth()
+
+    @staticmethod
+    def to_checksum_address(addr):
+        return addr
+
+
+# ---- installer -------------------------------------------------------------
+
+def install(ecld_state, caller=None, identity_priv=None, bucket="ecld-local",
+            contract_address="0xLOCAL", file_prefix=".ecld-esr-local"):
+    """Wire the emulator into the ecld_state module for local testing.
+
+    After this, StateRegistry() works fully in-process. `file_prefix` gives two
+    small JSON files (state blobs + registry) so state persists across runs;
+    pass None to keep everything in-memory only.
+    """
+    swift_file = (file_prefix + ".swift.json") if file_prefix else None
+    reg_file = (file_prefix + ".registry.json") if file_prefix else None
+    swift = MemSwift(file=swift_file)
+    reg = MemRegistry(file=reg_file)
+    web3 = MemWeb3(reg)
+
+    if identity_priv is None:
+        # A fixed, well-known LOCAL test identity -- stable wallet_address across
+        # runs. NOT a real key; local testing only.
+        identity_priv = b"ecld-local-test-identity-key-0001"
+
+    ecld_state.configure(
+        identity_priv=identity_priv,
+        swift_stream_service=swift,
+        bucket=bucket,
+        contract_address=contract_address,
+        web3=web3,
+        caller=caller,
+    )
+    # The node applies commitFor on-chain in real mode; locally, apply it here.
+    ecld_state.set_local_commit_apply(
+        lambda enclave, key_hash, cid, expected_version, nonce=0:
+            reg.apply_commit(enclave, key_hash, cid, expected_version, nonce))
+    return {"swift": swift, "registry": reg, "web3": web3}

package/pynithy/build/securelock/src/esr_wallet.py

@@ -0,0 +1,150 @@
+"""ESR identity wallet derivation (ESR RFC §5.1).
+
+The enclave's Ethereum wallet is derived from the enclave's IDENTITY PRIVATE
+KEY (the cert key), never from MR_ENCLAVE:
+
+    eth_priv    = keccak256(DOMAIN_SEP || identity_priv_der)   # secp256k1 scalar
+    eth_address = address(secp256k1(eth_priv))
+
+Why derive instead of reusing the cert key: the cert is secp384r1 (P-384) and
+Ethereum signing requires secp256k1, so a P-384 key can never sign a
+transaction. Deriving from the identity key means the wallet inherits the
+identity's security properties automatically:
+
+  * mainnet — identity key is the CAS-provisioned secret, so the wallet is
+    enclave-only and stable across every node running this MRENCLAVE.
+  * testnet — identity key is derived from MR_SIGNER/MR_ENCLAVE, both PUBLIC,
+    so the wallet is public too. Functional testing only; is_secret_identity()
+    reports False and callers must warn loudly (RFC §7).
+
+DOMAIN_SEP keeps this key from colliding with any other use of the identity
+key; a second separator derives the state-encryption key in a later phase.
+
+SECURITY: nothing here may serialize, log or return the private key. The only
+value that ever leaves the enclave is the ADDRESS (RFC §5.2) — that is what
+makes the wallet fundable and readable without weakening secrecy.
+"""
+
+import hashlib
+
+# The wallet PRIVATE key derivation is deliberately not part of the public
+# surface: the client payload is exec'd inside this image and can import any
+# module here, so an exported key-derivation helper would hand untrusted code a
+# ready-made way to materialize the ESR private key. Only the ADDRESS leaves
+# this module (RFC §5.2); _derive_wallet_private_key stays an implementation
+# detail of derive_wallet_address.
+__all__ = [
+    "DOMAIN_SEP",
+    "derive_wallet_address",
+    "is_secret_identity",
+    "INSECURE_IDENTITY_WARNING",
+]
+
+DOMAIN_SEP = b"ethernity-cloud/esr-wallet/v1"
+
+# secp256k1 group order; a valid private scalar is in [1, N-1].
+_SECP256K1_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+
+
+def _keccak256(data: bytes) -> bytes:
+    """Keccak-256 (Ethereum's hash), not SHA3-256."""
+    try:
+        from Crypto.Hash import keccak  # pycryptodome
+
+        h = keccak.new(digest_bits=256)
+        h.update(data)
+        return h.digest()
+    except ImportError:
+        from eth_hash.auto import keccak as eth_keccak  # web3 dependency
+
+        return eth_keccak(data)
+
+
+def _derive_wallet_private_key(identity_priv_der: bytes) -> bytes:
+    """32-byte secp256k1 private key derived from the enclave identity key.
+
+    Kept private to this module's callers; never log or transmit the result.
+    """
+    if not identity_priv_der:
+        raise ValueError("empty enclave identity key; cannot derive ESR wallet")
+    digest = _keccak256(DOMAIN_SEP + identity_priv_der)
+    # Astronomically unlikely, but a scalar of 0 or >= N is invalid: re-hash
+    # until valid so derivation is total rather than probabilistically broken.
+    while True:
+        scalar = int.from_bytes(digest, "big")
+        if 0 < scalar < _SECP256K1_N:
+            return digest
+        digest = _keccak256(DOMAIN_SEP + digest)
+
+
+def derive_wallet_address(identity_priv_der: bytes) -> str:
+    """Checksummed 0x address of the enclave's ESR wallet (safe to publish)."""
+    priv = _derive_wallet_private_key(identity_priv_der)
+    try:
+        from eth_keys import keys
+
+        return keys.PrivateKey(priv).public_key.to_checksum_address()
+    except ImportError:
+        # eth_account ships with the runner dependency chain and is always
+        # present in the enclave image; use it when eth_keys is unavailable.
+        from eth_account import Account
+
+        return Account.from_key(priv).address
+
+
+def is_secret_identity(network_type: str, attested: bool = False) -> bool:
+    """True only when the identity key is genuinely unpredictable to outsiders.
+
+    `attested` is whether this build is provisioned by a CAS (its key comes
+    from the CAS session): true on mainnet and on a testnet whose enclaves are
+    attested by the ethernity-cas validator set.
+
+    This is NOT "is the enclave genuine" — SGX protects enclave memory on every
+    network. It is the narrower question the ESR wallet depends on: could
+    someone outside the enclave reproduce the private key?
+
+    The distinction is ATTESTATION, not SGX. Both networks run the identical
+    in-enclave generator (get_sgx_report.c) on real SGX hardware, so at runtime
+    a node operator cannot read the key out of enclave memory on either.
+
+      * mainnet — CAS attests the enclave (DCAP quote verified) before the
+        identity is trusted, so a key is only accepted from a genuine, measured
+        enclave. The private key is effectively enclave-only: reproducing the
+        derivation outside a real attested enclave yields a key nothing accepts.
+        Intended posture; needs nothing from ESR.
+      * testnet — NO attestation. The enclave still runs on SGX and still
+        generates the keypair with the same algorithm, but nothing verifies the
+        MRENCLAVE, and the derivation input (MR_ENCLAVE) is public. So anyone
+        who rebuilds the image can reproduce the keypair. This is a deliberate
+        testnet tradeoff (real enclave execution for functional testing without
+        the CAS dependency) — not a bug. Treat testnet ESR wallets as
+        disposable; do not fund them with real value.
+
+    What would make the testnet key genuinely exclusive is a secret INPUT that
+    never leaves the CPU (EGETKEY / sealing key) OR requiring attestation on
+    testnet too. Encrypting or obfuscating the generator does NOT achieve this:
+    without attestation, an attacker doesn't reverse the code — they run the
+    published image (it is on IPFS, MRENCLAVE on-chain) and observe the key.
+    """
+    import os
+
+    override = os.getenv("ESR_IDENTITY_SECRET", "").strip().lower()
+    if override in ("1", "true", "yes"):
+        return True
+    if override in ("0", "false", "no"):
+        return False
+    # Secrecy tracks attestation, not the network name: mainnet is attested,
+    # and so is a testnet whose securelock is provisioned by a CAS.
+    return attested or str(network_type).strip().lower() == "mainnet"
+
+
+INSECURE_IDENTITY_WARNING = (
+    "[TESTNET-INSECURE] This network runs the enclave on SGX but WITHOUT "
+    "attestation, so the ESR wallet's keypair — though generated inside the "
+    "enclave — is reproducible by anyone who rebuilds the image (its derivation "
+    "input, MR_ENCLAVE, is public and nothing verifies the enclave). This is a "
+    "deliberate testnet tradeoff, not a defect. Treat the wallet as disposable "
+    "and do not fund it with real value. (An attested testnet build can set "
+    "ESR_IDENTITY_SECRET=1 to "
+    "suppress this warning.)"
+)