nervur 0.12.0 → 0.13.0

package/ground.mjs

@@ -1,17 +1,36 @@
 import { ADMIN } from './admin.mjs';
-import { Being, Compartment, Registry, SUCCESSION, make, rootFor, spend } from './being.mjs';
+import {
+  Being,
+  Compartment,
+  Registry,
+  SUCCESSION,
+  make,
+  rootFor,
+  spend,
+  successionOf,
+} from './being.mjs';
 import { Blueprint, composed, coreClass } from './blueprint.mjs';
 import { Client } from './client.mjs';
 import { Contracts } from './contract.mjs';
-import { Memory, Paths, Wire } from './modules.mjs';
+import { Memory } from './modules.mjs';
 import { Mcp, Pointer } from './pointer.mjs';
 import { Program } from './program.mjs';
-import { Stamp, Tools } from './tools.mjs';
+import { Bytes, Stamp, Tools } from './tools.mjs';
 import { Voice } from './voice.mjs';
 
 const GROUND = 'Ground';
 
-const FLOOR = ['blueprints', 'cells', 'contracts', 'keychain', 'paths', 'watch', 'wire'];
+const FLOOR = [
+  'blueprints',
+  'cells',
+  'cipher',
+  'contracts',
+  'keychain',
+  'moved',
+  'paths',
+  'watch',
+  'wire',
+];
 
 const UNPROVEN = 'ground/unproven/';
 
@@ -19,7 +38,11 @@ const HEIR = 'ground/heir';
 
 const commits = (cells, bundle) => {
   const boxPk = bundle?.heirBoxPk;
-  if (typeof boxPk !== 'string' || Buffer.from(boxPk, 'base64').length !== 32) {
+  try {
+    if (typeof boxPk !== 'string' || Bytes.unbase64(boxPk).length !== 32) {
+      return undefined;
+    }
+  } catch {
     return undefined;
   }
   cells.put(HEIR, { boxPk, nextPkHash: bundle.nextPkHash });
@@ -43,8 +66,8 @@ const unprovenAt = (cells) => (at) => {
 
 const unprovenRows = (cells) => cells.keys(UNPROVEN).map((row) => cells.peek(row));
 
-const install = ({ cells, keychain, program, bundle }) => {
-  if (bundle?.next !== undefined) {
+const install = ({ cells, keychain, program, bundle, cipher }) => {
+  if (cells.peek('ground/admin') !== undefined || bundle?.next !== undefined) {
     return undefined;
   }
   const voice = Voice.revive(bundle ?? {});
@@ -57,13 +80,13 @@ const install = ({ cells, keychain, program, bundle }) => {
   if (sealed === undefined) {
     return undefined;
   }
-  make({ memory, voice, address, program });
+  make({ memory, voice, address, program, cipher });
   cells.put('ground/admin', { address, sealed });
   commits(cells, bundle);
   return address;
 };
 
-const succeeds = ({ adminMine, adminVoice, address, bundle, cells, keychain, memory }) => {
+const succeeds = ({ adminMine, adminVoice, address, bundle, cells, cipher, keychain, memory }) => {
   if (bundle?.next !== undefined) {
     return undefined;
   }
@@ -72,21 +95,22 @@ const succeeds = ({ adminMine, adminVoice, address, bundle, cells, keychain, mem
   if (heir === undefined || committed?.value !== Tools.digest(heir.pk)) {
     return undefined;
   }
-  const root = rootFor({ memory, voice: adminVoice, address });
+  const root = rootFor({ memory, voice: adminVoice, address, cipher });
   const sealed = root === undefined ? undefined : keychain.seal(heir.pack());
   if (sealed === undefined) {
     return undefined;
   }
   const rewrapped = adminMine.write(`keyring/${Tools.address(heir.pk)}`, {
-    boxPk: Buffer.from(heir.boxPk).toString('base64'),
-    wrapped: Voice.sealTo(heir.boxPk, root.toString('base64')),
+    boxPk: Bytes.base64(heir.boxPk),
+    wrapped: Voice.sealTo(heir.boxPk, Bytes.base64(root), cipher),
   });
   if (rewrapped === undefined) {
     return undefined;
   }
   const version = committed.version + 1;
-  const handover = { at: address, next: Buffer.from(heir.pk).toString('hex'), v: version };
-  const certified = adminMine.write(`${SUCCESSION}${version}`, {
+  const certV = successionOf(memory, address).length + 1;
+  const handover = { at: address, next: Tools.address(heir.pk), v: certV };
+  const certified = adminMine.write(`${SUCCESSION}${certV}`, {
     ...handover,
     sig: adminVoice.sign(Tools.canon(handover)),
   });
@@ -96,7 +120,7 @@ const succeeds = ({ adminMine, adminVoice, address, bundle, cells, keychain, mem
   const claim = {
     address,
     nextPkHash: heir.nextPkHash,
-    pk: Buffer.from(heir.pk).toString('hex'),
+    pk: Bytes.hex(heir.pk),
     version,
   };
   if (memory.replace({ ...claim, sig: heir.sign(Tools.canon(claim)) }) === undefined) {
@@ -112,7 +136,14 @@ const succeeds = ({ adminMine, adminVoice, address, bundle, cells, keychain, mem
 const Ground = (modules = {}, { span } = {}) => {
   const cells = modules.cells;
   const keychain = modules.keychain;
-  if (cells === undefined || keychain?.seal === undefined || keychain?.unseal === undefined) {
+  const cipher = modules.cipher;
+  if (
+    cells === undefined ||
+    keychain?.seal === undefined ||
+    keychain?.unseal === undefined ||
+    cipher?.seal === undefined ||
+    cipher?.unseal === undefined
+  ) {
     return undefined;
   }
 
@@ -134,7 +165,7 @@ const Ground = (modules = {}, { span } = {}) => {
   const installed = cells.peek('ground/admin');
   if (installed === undefined) {
     return Object.freeze({
-      init: (bundle) => install({ cells, keychain, program, bundle }),
+      init: (bundle) => install({ cells, keychain, program, bundle, cipher: modules.cipher }),
     });
   }
   const bundle = keychain.unseal(installed.sealed);
@@ -155,17 +186,22 @@ const Ground = (modules = {}, { span } = {}) => {
   };
 
   const address = installed.address;
-  const memory = Memory(cells, unprovenAt(cells));
-  const paths = modules.paths ?? Paths(new Map());
-  const wire = modules.wire ?? Wire();
+  const memory = Memory(cells, unprovenAt(cells), modules.moved);
+  const paths = modules.paths ?? Object.freeze({ find: () => undefined, publish: () => undefined });
+  const wire =
+    modules.wire ??
+    Object.freeze({
+      carry: async (endpoint, envelope) =>
+        typeof endpoint === 'function' ? endpoint(envelope) : undefined,
+    });
 
   const stamp = Stamp();
   const boundFor = (voice) =>
     Object.fromEntries(
       bound.map(([name, one]) => [
         name,
-        Pointer(written.get(one.contract).sdl, (source, variables) =>
-          deliver(Tools.envelope(voice, one.at, { ask: { source, variables } }, stamp())),
+        Pointer(written.get(one.contract).sdl, async (source, variables) =>
+          deliver(await Tools.envelope(voice, one.at, { ask: { source, variables } }, stamp())),
         ),
       ]),
     );
@@ -199,9 +235,10 @@ const Ground = (modules = {}, { span } = {}) => {
     memory,
     voice: adminVoice,
     address,
-    root: rootFor({ memory, voice: adminVoice, address }),
+    root: rootFor({ memory, voice: adminVoice, address, cipher: modules.cipher }),
     classOf: (key) =>
       Program(memory.read(address, 'program')?.value)?.classOf(key) ?? coreClass(key),
+    cipher: modules.cipher,
   });
 
   const receive = async (envelope, token) => {
@@ -223,6 +260,7 @@ const Ground = (modules = {}, { span } = {}) => {
     paths.publish(at, undefined);
     if (voice === undefined) {
       cells.drop(`${at}/`);
+      modules.moved?.(at);
       return undefined;
     }
     return spend({ memory, voice, address: at });
@@ -236,16 +274,30 @@ const Ground = (modules = {}, { span } = {}) => {
     if (one.at === undefined) {
       return null;
     }
-    const seen = await deliver(Tools.envelope(adminVoice, one.at, { describe: {} }, stamp()));
+    const seen = await deliver(await Tools.envelope(adminVoice, one.at, { describe: {} }, stamp()));
     return seen?.body?.sdl === undefined
       ? false
       : written.get(one.contract).satisfies(seen.body.sdl);
   };
 
+  let adminDoor;
+  const buildAdmin = () =>
+    Being({
+      address,
+      cipher: modules.cipher,
+      deliver: (envelope) => deliver(envelope),
+      modules: modulesFor(adminVoice, adminDeclared()),
+      registry,
+      span,
+      vouched,
+      voice: adminVoice,
+      watch,
+    });
   const registry = Registry({
     memory,
     adminMine,
     address,
+    cipher: modules.cipher,
     deliver: (envelope) => deliver(envelope),
     modules: offeredNames,
     modulesFor,
@@ -255,18 +307,16 @@ const Ground = (modules = {}, { span } = {}) => {
     vouched,
     attest,
     watch,
+    extended: () => {
+      adminDoor = undefined;
+    },
   });
-  const admin = (envelope, token) =>
-    Being({
-      address,
-      deliver: (envelope) => deliver(envelope),
-      modules: modulesFor(adminVoice, adminDeclared()),
-      registry,
-      span,
-      vouched,
-      voice: adminVoice,
-      watch,
-    })(envelope, token);
+  const admin = (envelope, token) => {
+    if (adminDoor === undefined) {
+      adminDoor = buildAdmin();
+    }
+    return adminDoor(envelope, token);
+  };
 
   announce(address);
   for (const key of adminMine.list('identity/custody/')) {
@@ -284,7 +334,16 @@ const Ground = (modules = {}, { span } = {}) => {
     address,
     receive,
     rotate: (bundle) =>
-      succeeds({ adminMine, adminVoice, address, bundle, cells, keychain, memory }),
+      succeeds({
+        adminMine,
+        adminVoice,
+        address,
+        bundle,
+        cells,
+        cipher: modules.cipher,
+        keychain,
+        memory,
+      }),
     serve: (voice) => {
       const client = Client({ voice, deliver, resolve });
       const sdlOf = async (at) => (await client.describe(at))?.body?.sdl;

package/index.mjs

@@ -13,8 +13,8 @@ export {
 export { Client, speaking } from './client.mjs';
 export { Contract, Contracts } from './contract.mjs';
 export { FLOOR, GROUND, Ground } from './ground.mjs';
-export { Cells, Clock, Dns, Entropy, Keychain, Memory, Paths, Wire } from './modules.mjs';
+export { Memory } from './modules.mjs';
 export { Mcp, Pointer } from './pointer.mjs';
 export { Program } from './program.mjs';
-export { MEASURE, SPAN, Stamp, Tools } from './tools.mjs';
+export { Bytes, MEASURE, SPAN, Stamp, Tools } from './tools.mjs';
 export { Voice } from './voice.mjs';

package/modules.mjs

@@ -1,38 +1,13 @@
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { Tools } from './tools.mjs';
+import { Bytes, Tools } from './tools.mjs';
 
-const Cells = ({ file } = {}) => {
-  const cells = new Map(
-    file && existsSync(file) ? Object.entries(JSON.parse(readFileSync(file, 'utf8'))) : [],
-  );
-  const flush = () => {
-    if (file) {
-      writeFileSync(`${file}.next`, JSON.stringify(Object.fromEntries(cells)));
-      renameSync(`${file}.next`, file);
-    }
-  };
-  return Object.freeze({
-    drop: (prefix) => {
-      for (const cell of [...cells.keys()].filter((one) => one.startsWith(prefix))) {
-        cells.delete(cell);
-      }
-      flush();
-    },
-    dump: () => JSON.stringify(Object.fromEntries(cells)),
-    keys: (prefix) => [...cells.keys()].filter((cell) => cell.startsWith(prefix)),
-    peek: (cell) => cells.get(cell),
-    put: (cell, held) => {
-      cells.set(cell, held);
-      flush();
-    },
-  });
-};
-
-const Memory = (cells, unproven) => {
+// The ground's own machinery over its cells. Every implementation a host
+// supplies — cells, keychain, cipher, paths, wire — belongs to that host's
+// floor and never to the core (X, Everything is a module).
+const Memory = (cells, unproven, moved) => {
   const held = (address, key) => cells.peek(`${address}/${key}`);
   const writerAt = (address) => {
     const chain = held(address, 'chain/pk');
-    return chain === undefined ? Tools.pkOf(address) : Buffer.from(chain.value, 'hex');
+    return chain === undefined ? Tools.pkOf(address) : Bytes.unhex(chain.value);
   };
   return Object.freeze({
     list: (address, prefix) =>
@@ -42,16 +17,17 @@ const Memory = (cells, unproven) => {
 
     replace: ({ address, pk, nextPkHash, sig }) => {
       const committed = held(address, 'chain/nextPkHash');
-      if (committed === undefined || Tools.digest(Buffer.from(pk, 'hex')) !== committed.value) {
+      if (committed === undefined || Tools.digest(Bytes.unhex(pk)) !== committed.value) {
         return undefined;
       }
       const version = committed.version + 1;
       const claim = { address, nextPkHash, pk, version };
-      if (!Tools.verifies(Buffer.from(pk, 'hex'), Tools.canon(claim), sig)) {
+      if (!Tools.verifies(Bytes.unhex(pk), Tools.canon(claim), sig)) {
         return undefined;
       }
       cells.put(`${address}/chain/pk`, { value: pk, version });
       cells.put(`${address}/chain/nextPkHash`, { value: nextPkHash, version });
+      moved?.(address);
       return version;
     },
 
@@ -68,45 +44,12 @@ const Memory = (cells, unproven) => {
         return undefined;
       }
       cells.put(`${address}/${key}`, { value, version });
+      if (!key.startsWith('refs/')) {
+        moved?.(address);
+      }
       return version;
     },
   });
 };
 
-const Clock = (ticks) => {
-  let at = 0;
-  return Object.freeze({ now: () => ticks[Math.min(at++, ticks.length - 1)] });
-};
-
-const Entropy = (grains) => {
-  let at = 0;
-  return Object.freeze({ grain: () => grains[Math.min(at++, grains.length - 1)] });
-};
-
-const Keychain = (secret) =>
-  Object.freeze({
-    seal: (value) => {
-      try {
-        return Tools.seal(secret, value);
-      } catch {
-        return undefined;
-      }
-    },
-    unseal: (sealed) => Tools.unseal(secret, sealed),
-  });
-
-const Dns = () => new Map();
-
-const Paths = (dns) =>
-  Object.freeze({
-    find: (address) => dns.get(address),
-    publish: (address, endpoint) =>
-      endpoint === undefined ? dns.delete(address) : dns.set(address, endpoint),
-  });
-
-const Wire = () =>
-  Object.freeze({
-    carry: async (endpoint, envelope) => (endpoint === undefined ? undefined : endpoint(envelope)),
-  });
-
-export { Cells, Clock, Dns, Entropy, Keychain, Memory, Paths, Wire };
+export { Memory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "A distributed system of sovereign beings — one door, one question: by whose authority.",
   "license": "Apache-2.0",
   "author": "Razvan Gherghina",
@@ -11,12 +11,15 @@
   },
   "files": [
     "*.mjs",
-    "NOTICE"
+    "GETTING-STARTED.md",
+    "NOTICE",
+    "SECURITY.md"
   ],
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
+    "@noble/curves": "2.3.0",
     "graphql": "^17.0.2"
   }
 }

package/tools.mjs

@@ -1,13 +1,57 @@
-import {
-  createCipheriv,
-  createDecipheriv,
-  createHash,
-  createPublicKey,
-  randomBytes,
-  verify,
-} from 'node:crypto';
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { sha256 } from '@noble/hashes/sha2.js';
 
-const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const HEX = '0123456789abcdef';
+
+const utf8 = new TextEncoder();
+const text8 = new TextDecoder();
+
+// Buffer is Node's alone. Every byte string here is a Uint8Array, and these
+// are the encodings the substrate names: hex on a digest, base64 on a
+// signature, utf8 under canon.
+const Bytes = Object.freeze({
+  base64: (bytes) => {
+    let binary = '';
+    for (const byte of bytes) {
+      binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+  },
+  concat: (parts) => {
+    const whole = new Uint8Array(parts.reduce((run, one) => run + one.length, 0));
+    let at = 0;
+    for (const one of parts) {
+      whole.set(one, at);
+      at += one.length;
+    }
+    return whole;
+  },
+  equal: (one, other) => one.length === other.length && one.every((byte, at) => byte === other[at]),
+  hex: (bytes) => {
+    let out = '';
+    for (const byte of bytes) {
+      out += HEX[byte >> 4] + HEX[byte & 15];
+    }
+    return out;
+  },
+  of: (value) => utf8.encode(value),
+  read: (bytes) => text8.decode(bytes),
+  unbase64: (value) => {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let at = 0; at < binary.length; at += 1) {
+      bytes[at] = binary.charCodeAt(at);
+    }
+    return bytes;
+  },
+  unhex: (value) => {
+    const bytes = new Uint8Array(value.length >> 1);
+    for (let at = 0; at < bytes.length; at += 1) {
+      bytes[at] = Number.parseInt(value.substr(at << 1, 2), 16);
+    }
+    return bytes;
+  },
+});
 
 const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
 
@@ -70,21 +114,23 @@ const unbase32 = (text) => {
       bits -= 8;
     }
   }
-  return Buffer.from(out);
+  return Uint8Array.from(out);
 };
 
 const Tools = Object.freeze({
   address: (pk) => {
-    const payload = Buffer.concat([Buffer.from([VERSION_G]), pk]);
+    const payload = Bytes.concat([Uint8Array.of(VERSION_G), pk]);
     const crc = crc16(payload);
-    return base32(Buffer.concat([payload, Buffer.from([crc & 0xff, crc >> 8])]));
+    return base32(Bytes.concat([payload, Uint8Array.of(crc & 0xff, crc >> 8)]));
   },
-  canon: (claim) => Buffer.from(JSON.stringify(ordered(claim))),
-  derive: (root, label) => createHash('sha256').update(root).update(label).digest(),
-  digest: (bytes) => createHash('sha256').update(bytes).digest('hex'),
-  envelope: (voice, to, op, seq) => {
+  canon: (claim) => Bytes.of(JSON.stringify(ordered(claim))),
+  // The label arrives as text and the digest is over its utf8 bytes, which is
+  // the byte string the substrate has always hashed.
+  derive: (root, label) => sha256.create().update(root).update(Bytes.of(label)).digest(),
+  digest: (bytes) => Bytes.hex(sha256(bytes)),
+  envelope: async (voice, to, op, seq) => {
     const from = Tools.address(voice.pk);
-    return { from, op, seq, sig: voice.sign(Tools.canon({ from, op, seq, to })), to };
+    return { from, op, seq, sig: await voice.sign(Tools.canon({ from, op, seq, to })), to };
   },
   pkOf: (address) => {
     const bytes = typeof address === 'string' && address.length === 56 ? unbase32(address) : null;
@@ -93,39 +139,12 @@ const Tools = Object.freeze({
     }
     const payload = bytes.subarray(0, 33);
     const checksum = bytes[33] | (bytes[34] << 8);
-    return crc16(payload) === checksum ? Buffer.from(payload.subarray(1)) : null;
-  },
-  seal: (secret, value) => {
-    const iv = randomBytes(12);
-    const cipher = createCipheriv('aes-256-gcm', secret, iv);
-    const sealed = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()]);
-    return Buffer.concat([iv, cipher.getAuthTag(), sealed]).toString('base64');
-  },
-  secret: () => randomBytes(32),
-  unseal: (secret, sealed) => {
-    try {
-      const bytes = Buffer.from(sealed, 'base64');
-      const decipher = createDecipheriv('aes-256-gcm', secret, bytes.subarray(0, 12));
-      decipher.setAuthTag(bytes.subarray(12, 28));
-      return JSON.parse(
-        Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString('utf8'),
-      );
-    } catch {
-      return undefined;
-    }
+    return crc16(payload) === checksum ? payload.slice(1) : null;
   },
+  secret: () => crypto.getRandomValues(new Uint8Array(32)),
   verifies: (pk, bytes, sig) => {
     try {
-      return verify(
-        null,
-        bytes,
-        createPublicKey({
-          key: Buffer.concat([ED25519_SPKI_PREFIX, pk]),
-          format: 'der',
-          type: 'spki',
-        }),
-        Buffer.from(sig, 'base64'),
-      );
+      return ed25519.verify(Bytes.unbase64(sig), bytes, pk);
     } catch {
       return false;
     }
@@ -140,4 +159,4 @@ const Stamp = () => {
   };
 };
 
-export { MEASURE, SPAN, Stamp, Tools };
+export { Bytes, MEASURE, SPAN, Stamp, Tools };