nervur 0.12.0 → 0.14.0

package/GETTING-STARTED.md

@@ -0,0 +1,111 @@
+# Getting started — two castles
+
+Picture a castle: one gate, its own residents, its own law. A **ground** is
+the castle — one sovereign process, one handler where every letter arrives.
+Its residents are **beings**; its capabilities are **modules**; the ground
+under it is a **floor** — a filesystem, or a browser's IndexedDB — and the
+stance it takes toward the world is its **terrain**. This page raises two
+castles on two terrains and has them speak: a **mountain** (a server, always
+reachable, always remembering) and a **house of cards** (a browser tab,
+raised in seconds, holding what it can afford to lose). Same castle, same
+law, different ground under it.
+
+Everything below runs today — the bench drives this exact story in
+`bench/worlds/story/`.
+
+## The mountain
+
+The machine's raise is one config and one daemon —
+[`nervurd`](https://www.npmjs.com/package/nervurd) is the host, and its
+README is the operator's full page. The five-minute shape:
+
+```sh
+npm install -g nervurd
+nervur self mint --self ./hand.json --heir ./heir.json
+nervur init --config ./castle.json --self ./hand.json
+NERVUR_SECRET=... nervurd --config ./castle.json
+```
+
+The config names the shelf, the door, the secret's environment variable,
+and the modules — the castle's capabilities, chosen by you:
+
+```json
+{
+  "cells": "/var/lib/nervur/castle.json",
+  "listen": { "host": "127.0.0.1", "port": 7001 },
+  "secret": "NERVUR_SECRET",
+  "modules": {}
+}
+```
+
+Keep the heir off the machine. Whoever takes the machine takes what the
+castle holds today; the heir is why they can never become it tomorrow.
+
+## The house of cards
+
+The browser's raise is two calls from
+[`@nervur-org/floor-web`](https://www.npmjs.com/package/@nervur-org/floor-web),
+because a tab closes constantly and the two acts must not blur:
+
+```js
+import { found, wake } from '@nervur-org/floor-web';
+
+// Once, ever: mint the identity, stand the castle, get custody back.
+let kept;
+const castle = found({ keep: (dump) => (kept = dump) });
+// castle.address — the name; castle.custody — the hand, the heir, the
+// secret: yours to keep (IndexedDB, or a mountain you trust), never the
+// ground's.
+
+// Every session after: same name, same residents, no identity act.
+// wake hands back the standing ground itself — woken.address is the name.
+const woken = wake({ held: kept, secret: castle.custody.secret });
+```
+
+Where `kept` and `custody` live is your choice, under this terrain's honest
+limit: a browser may evict what it keeps — a card castle holds what it can
+afford to lose, and keeps what is precious in its relationship with a
+mountain.
+
+## They speak
+
+A letter is a letter on every terrain: one signed envelope, carried
+however the two castles can reach each other — here, `fetch` to the
+mountain's door. First the mountain's keeper invites the card castle's
+founder (one signed act at the admin door — the CLI, or any client the
+keeper holds), and then the founder asks from the browser:
+
+```js
+import { Client, Tools, Voice } from 'nervur';
+
+const me = Voice.revive(castle.custody.hand);
+const talk = Client({
+  voice: me,
+  deliver: async (envelope) => {
+    const res = await fetch('http://127.0.0.1:7001', {
+      body: JSON.stringify(envelope),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    });
+    return res.status === 200 ? res.json() : undefined;
+  },
+});
+
+const heard = await talk.ask(mountainAddress, '{ census { active } }');
+```
+
+The client verifies every answer from the address alone — the mountain's
+word arrives signed, and a broken or missing signature is dropped exactly
+like silence. A stranger who was never invited gets silence too, and cannot
+tell refusal from absence. That is the whole protocol: **say who you are,
+name whom you seek, and the castle answers or keeps quiet.**
+
+## Where to go next
+
+- [`nervur`'s README](README.md) — the library underneath both castles.
+- [`nervurd`'s README](../nervurd/README.md) — the operator's page: checks,
+  rotation, backups, the door's full behaviour.
+- [`@nervur-org/floor-web`](../floor-web/README.md) — the web floor's
+  terrain contract, founding and waking in full.
+- [`@nervur-org/species`](../species/README.md) — blueprints your castles
+  grow beings from.

package/README.md

@@ -1,23 +1,40 @@
 # Nervur
 
-The library. **A distributed system of sovereign beings**: an address is its
-own verification key, authority is a signature, and every relationship is
-one ref with declared rights — so a reference cannot be forged and no
-ambient authority exists anywhere. A ground is one sovereign process holding
-many beings — it creates them and it destroys them, and it exposes exactly
-one handler where every message for every being arrives. A being is one
-function closed over its own cells; the door asks by whose authority and
-refuses every other question. The lineage is the object-capability
-tradition — CapTP, the actor model — with one honest departure: the door
-verifies who is calling, and rights are declared per reference. Pure
-Crockford JavaScript — factory functions, closures for privacy, no `this`,
-no classes, frozen surfaces — on `node:` built-ins, plus `graphql` for the
-one thing that would be madness to hand-roll: the schema and its execution.
+The library. Picture a castle: one gate, its own residents, its own law.
+**A ground is the castle** — one sovereign process holding many beings,
+exposing exactly one handler where every message for every resident
+arrives. You arrive at the gate, say _I am X_ with your signature, and
+whom you seek travels inside the letter; the castle answers or keeps
+silence, and a resident that refuses you looks exactly like one that
+never lived there. The castle's capabilities are its **modules** — a
+resident uses only what its blueprint declares — and the terrain under
+the castle is a **floor**: a browser tab, a Linux daemon, a phone, an
+edge worker. The castle is a castle wherever it is built.
+
+Beneath the picture, the mechanics: an address is its own verification
+key, authority is a signature, and every relationship is one ref with
+declared rights — so a reference cannot be forged and no ambient
+authority exists anywhere. The door asks by whose authority and refuses
+every other question. The lineage is the object-capability tradition —
+CapTP, the actor model — with one honest departure: the door verifies who
+is calling, and rights are declared per reference. Pure Crockford
+JavaScript — factory functions, closures for privacy, no `this`, no
+classes, frozen surfaces — with no `node:` import anywhere, so the twelve
+files run wherever JavaScript does; three dependencies (`graphql` for the
+one thing that would be madness to hand-roll, `@noble/curves` and
+`@noble/hashes` for the arithmetic every host must agree on).
 
 ## Quickstart
 
-`npm install nervur` — what ships is this source, byte for byte, one
-dependency (`graphql`). The package is a library and carries no command;
+New to the whole thing? [GETTING-STARTED.md](GETTING-STARTED.md) raises
+two castles on two terrains — a server and a browser tab — and has them
+speak; the bench drives that exact story. What follows here is the
+library alone.
+
+`npm install nervur` — what ships is this source, byte for byte. The
+package is a library and carries no command; a ground also needs a floor
+(`@nervur-org/floor-machine` here) — the library is the law and the
+shape, and a host is what it stands on;
 the `nervur` command on an operator's PATH belongs to the
 [`nervurd`](../nervurd/README.md) package, its name twin. Construction is
 synchronous; every call through a door — `pointer`, `mcp`, `gql`, and each
@@ -25,7 +42,8 @@ function they hand back — is async. This runs today, lifted from the
 bench's own passing suites:
 
 ```js
-import { Cells, Ground, Keychain, Tools, Voice } from 'nervur';
+import { Cells, Cipher, Keychain } from '@nervur-org/floor-machine';
+import { Ground, Tools, Voice } from 'nervur';
 
 const DIARY = `({
   name: 'acme.diary',
@@ -49,7 +67,11 @@ const DIARY = `({
 })`;
 
 const secret = Buffer.from(process.env.NERVUR_SECRET, 'base64'); // 32 bytes, minted once with Tools.secret()
-const shelf = { cells: Cells({ file: 'ground.json' }), keychain: Keychain(secret) };
+const shelf = {
+  cells: Cells({ file: 'ground.json' }),
+  cipher: Cipher(),
+  keychain: Keychain(secret),
+};
 
 const heir = Voice(); // keep this one somewhere the machine is not
 const self = Voice(Tools.digest(heir.pk)); // and hand the ground only this
@@ -122,7 +144,11 @@ three things while hiding everything it is made of:
   ground arrives here and routes on the envelope's `to`. An address the
   ground does not hold is silence. A host module that listens on a port, or
   an app shell that calls in process, hands its envelopes to this and
-  nothing else — the library never opens a socket.
+  nothing else — the library never opens a socket. `receive` answers the
+  signed `{ body, sig }` or `undefined` for silence; over HTTP, carry the
+  answer as the 200 response body and silence however you like (`nervurd`
+  uses an empty `204`) — no status code carries meaning, and a caller
+  trusts nothing but a verified signed answer.
 - `serve(voice)` — authority established once, and every face inherits it.
 
 A fresh ground has no identity, and no door for anyone to reach first: it

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+This package answers one question — by whose authority — and a hole in that
+answer is the most serious bug it can have.
+
+Report vulnerabilities privately to **<security@nervur.com>**. Do not open a
+public report. State what you ran, what you sent, and what answered; a
+proof of concept is welcome but not required.
+
+A person reads every report. Fixes ship as releases on the live 0.x line,
+and the report is credited if you want it to be.

package/being.mjs

@@ -1,10 +1,10 @@
 import { ADMIN } from './admin.mjs';
 import { OPEN, STRUCTURAL, composed, coreClass } from './blueprint.mjs';
 import { Program } from './program.mjs';
-import { MEASURE, SPAN, Stamp, Tools } from './tools.mjs';
+import { Bytes, MEASURE, SPAN, Stamp, Tools } from './tools.mjs';
 import { Voice } from './voice.mjs';
 
-const Compartment = ({ memory, voice, address, root, classOf }) => {
+const Compartment = ({ memory, voice, address, root, classOf, cipher }) => {
   const held = (key) => memory.read(address, key);
   const sealed = (key) => {
     const kind = classOf(key);
@@ -25,7 +25,10 @@ const Compartment = ({ memory, voice, address, root, classOf }) => {
         return undefined;
       }
       const secret = sealed(key);
-      return secret === undefined ? cell.value : Tools.unseal(secret, cell.value);
+      if (secret === undefined) {
+        return cell.value;
+      }
+      return cipher === undefined ? undefined : cipher.unseal(secret, cell.value);
     },
     write: (key, plain) => {
       if (classOf(key) === undefined) {
@@ -35,7 +38,14 @@ const Compartment = ({ memory, voice, address, root, classOf }) => {
         return put(key, null);
       }
       const secret = sealed(key);
-      return put(key, secret === undefined ? plain : Tools.seal(secret, plain));
+      if (secret === undefined) {
+        return put(key, plain);
+      }
+      if (cipher === undefined) {
+        return undefined;
+      }
+      const shut = cipher.seal(secret, plain);
+      return shut === undefined ? undefined : put(key, shut);
     },
   });
 };
@@ -82,7 +92,7 @@ const custodial = (registry, fence) =>
         upgrade: (one) => (fence.open() ? registry.upgrade(one) : undefined),
       });
 
-const offered = (modules, program, mine) =>
+const offered = (modules, program, mine, seat) =>
   Object.freeze({
     ...Object.fromEntries(
       (program?.modules ?? [])
@@ -90,21 +100,57 @@ const offered = (modules, program, mine) =>
         .filter((name) => name !== 'memory' && modules[name] !== undefined)
         .map((name) => [name, modules[name]]),
     ),
-    memory: scoped(mine, program),
+    memory: scoped(mine, program, seat),
   });
 
 const grantable = (program) =>
   (program?.rights ?? [...STRUCTURAL, 'MEMBER']).filter((one) => !STRUCTURAL.includes(one));
 
-const referable = (mine, key, plain, program) => {
+const HORIZON = 7_776_000_000;
+
+const whole = (one) => Number.isSafeInteger(one) && one >= 0;
+
+const invitation = (plain, rights, program, seat) => {
+  const count = plain.count ?? 1;
+  const expiresAt = plain.expiresAt ?? 0;
+  if (!whole(count) || count < 1 || !whole(expiresAt)) {
+    return undefined;
+  }
+  const now = seat.now();
+  if (seat.administration) {
+    return count === 1 && expiresAt > 0 && expiresAt < now + HORIZON
+      ? { ...plain, count, expiresAt, rights }
+      : undefined;
+  }
+  const ceiling = program?.invites?.(rights);
+  if (ceiling !== undefined) {
+    if (ceiling.count > 0 && count > ceiling.count) {
+      return undefined;
+    }
+    if (ceiling.within > 0 && (expiresAt === 0 || expiresAt > now + ceiling.within)) {
+      return undefined;
+    }
+  }
+  return { ...plain, count, expiresAt, rights };
+};
+
+const referable = (mine, key, plain, program, seat) => {
   const rights = plain.rights ?? 'MEMBER';
   if (!grantable(program).includes(rights)) {
     return undefined;
   }
   if (key.startsWith('refs/pending/')) {
-    return { ...plain, rights };
+    return invitation(plain, rights, program, seat);
   }
   const held = mine.read(key);
+  if (
+    held?.nextPkHash != null &&
+    plain.nextPkHash !== undefined &&
+    plain.nextPkHash !== null &&
+    plain.nextPkHash !== held.nextPkHash
+  ) {
+    return undefined;
+  }
   return {
     ...plain,
     nextPkHash: plain.nextPkHash ?? held?.nextPkHash ?? null,
@@ -113,14 +159,14 @@ const referable = (mine, key, plain, program) => {
   };
 };
 
-const scoped = (mine, program) =>
+const scoped = (mine, program, seat) =>
   Object.freeze({
     classOf: mine.classOf,
     list: mine.list,
     read: mine.read,
     write: (key, plain) => {
       if (key.startsWith('refs/') && plain !== undefined) {
-        const guarded = referable(mine, key, plain, program);
+        const guarded = referable(mine, key, plain, program, seat);
         return guarded === undefined ? undefined : mine.write(key, guarded);
       }
       return key.startsWith('refs/') ||
@@ -131,10 +177,10 @@ const scoped = (mine, program) =>
     },
   });
 
-const rootFor = ({ memory, voice, address }) => {
+const rootFor = ({ memory, voice, address, cipher }) => {
   const cell = memory.read(address, `keyring/${Tools.address(voice.pk)}`);
-  const opened = cell === undefined ? undefined : voice.open(cell.value.wrapped);
-  return opened === undefined ? undefined : Buffer.from(opened, 'base64');
+  const opened = cell === undefined ? undefined : voice.open(cell.value.wrapped, cipher);
+  return opened === undefined ? undefined : Bytes.unbase64(opened);
 };
 
 const Port = ({ voice, mine, deliver, rights, stamp, lanes, fence }) => {
@@ -142,11 +188,19 @@ const Port = ({ voice, mine, deliver, rights, stamp, lanes, fence }) => {
     if (fence !== undefined && !fence.open()) {
       return undefined;
     }
-    const turn = (lanes.get(to) ?? Promise.resolve()).then(() => {
+    const turn = (lanes.get(to) ?? Promise.resolve()).then(async () => {
       const handle = mine.read(`handles/${to}`);
-      return deliver(
-        Tools.envelope(handle === undefined ? voice : Voice.revive(handle.face), to, op, stamp()),
+      const envelope = await Tools.envelope(
+        handle === undefined ? voice : Voice.revive(handle.face),
+        to,
+        op,
+        stamp(),
       );
+      const claim = Tools.digest(
+        Tools.canon({ from: envelope.from, op: envelope.op, seq: envelope.seq, to: envelope.to }),
+      );
+      const reply = await deliver(envelope);
+      return reply === undefined ? undefined : { ...reply, claim };
     });
     const settled = turn.then(
       () => undefined,
@@ -206,10 +260,21 @@ const successionOf = (memory, address) =>
     .filter((one) => one !== undefined)
     .sort((one, other) => one.v - other.v);
 
-const Being = ({ voice, address, deliver, modules, registry, span, vouched, watch }) => {
+const Being = ({
+  voice,
+  address,
+  cipher,
+  deliver,
+  modules,
+  registry,
+  administration,
+  span,
+  vouched,
+  watch,
+}) => {
   const held = spanOf(span);
   const memory = modules.memory;
-  const root = rootFor({ memory, voice, address });
+  const root = rootFor({ memory, voice, address, cipher });
   const source = memory.read(address, 'program')?.value;
   const program = source === undefined ? undefined : Program(source);
   const mine = Compartment({
@@ -218,16 +283,18 @@ const Being = ({ voice, address, deliver, modules, registry, span, vouched, watc
     address,
     root,
     classOf: (key) => program?.classOf(key) ?? coreClass(key),
+    cipher,
   });
   const succession = successionOf(memory, address);
   const stamp = Stamp();
+  const seat = Object.freeze({ administration: administration === true, now: stamp });
   const lanes = new Map();
-  const answer = (spoken) => {
+  const answer = (spoken, claim) => {
     const body = Tools.canon(spoken);
     if (body.length > MEASURE) {
       return undefined;
     }
-    const signed = { body: spoken, sig: voice.sign(body) };
+    const signed = { body: spoken, sig: voice.sign(Tools.canon({ body: spoken, claim })) };
     return succession.length === 0 ? signed : { ...signed, succession };
   };
   const note = (envelope, outcome) => {
@@ -251,6 +318,7 @@ const Being = ({ voice, address, deliver, modules, registry, span, vouched, watc
       try {
         const { from, op, seq, sig, to } = envelope;
         const claim = Tools.canon({ from, op, seq, to });
+        const claimDigest = Tools.digest(claim);
         const callerPk = Tools.pkOf(from);
         const proven =
           claim.length <= MEASURE &&
@@ -274,41 +342,50 @@ const Being = ({ voice, address, deliver, modules, registry, span, vouched, watc
           if (program !== undefined && !program.visible(rights)) {
             return undefined;
           }
-          return answer({
-            address,
-            digest: program?.digest,
-            rights,
-            sdl: program?.sdlFor(rights),
-          });
+          return answer(
+            {
+              address,
+              box: Bytes.base64(voice.boxPk),
+              digest: program?.digest,
+              rights,
+              sdl: program?.sdlFor(rights),
+            },
+            claimDigest,
+          );
         }
         if (op?.introspect !== undefined) {
           const seen = await program?.introspect(rights);
-          return seen === undefined ? undefined : answer({ introspection: seen });
+          return seen === undefined ? undefined : answer({ introspection: seen }, claimDigest);
         }
         if (op?.rotate !== undefined) {
           const rotated = rotates({ mine }, from, op.rotate.nextPkHash);
-          return rotated === undefined ? undefined : answer({ rotated });
+          return rotated === undefined ? undefined : answer({ rotated }, claimDigest);
         }
         if (op?.release !== undefined) {
           if (row === undefined) {
             return undefined;
           }
           mine.write(`refs/${from}`, undefined);
-          return answer({ released: from });
+          return answer({ released: from }, claimDigest);
         }
         if (op?.acceptInvite !== undefined) {
-          const offer = Tools.digest(Buffer.from(op.acceptInvite.proof, 'base64'));
+          const offer = Tools.digest(Bytes.unbase64(op.acceptInvite.proof));
           const pending = mine.read(`refs/pending/${offer}`);
-          if (pending === undefined || pending.spent) {
+          const now = stamp();
+          if (
+            pending === undefined ||
+            !(pending.count > 0) ||
+            (pending.expiresAt > 0 && now > pending.expiresAt)
+          ) {
             return undefined;
           }
-          mine.write(`refs/pending/${offer}`, { spent: true });
+          mine.write(`refs/pending/${offer}`, { ...pending, count: pending.count - 1 });
           mine.write(`refs/${from}`, {
             nextPkHash: op.acceptInvite.nextPkHash ?? null,
             rights: pending.rights,
             seen: seq ?? 0,
           });
-          return answer({ referred: from, rights: pending.rights });
+          return answer({ referred: from, rights: pending.rights }, claimDigest);
         }
         if (op?.ask === undefined || program === undefined || !program.visible(rights)) {
           return undefined;
@@ -320,7 +397,7 @@ const Being = ({ voice, address, deliver, modules, registry, span, vouched, watc
           program.ask({
             context: {
               from: program.caller ? from : undefined,
-              modules: offered(modules, program, turn),
+              modules: offered(modules, program, turn, seat),
               port: Port({ voice, mine: turn, deliver, fence, lanes, rights, stamp }),
               registry: custodial(registry, fence),
               rights,
@@ -329,7 +406,7 @@ const Being = ({ voice, address, deliver, modules, registry, span, vouched, watc
             variables: op.ask.variables,
           }),
         ).finally(fence.close);
-        return asked === undefined ? undefined : answer(asked);
+        return asked === undefined ? undefined : answer(asked, claimDigest);
       } catch {
         return undefined;
       }
@@ -352,18 +429,18 @@ const spend = ({ memory, voice, address }) => {
   return address;
 };
 
-const make = ({ memory, voice, address, program }) => {
+const make = ({ memory, voice, address, program, cipher }) => {
   const root = Tools.secret();
   const put = (key, value) => {
     const claim = { address, key, value, version: (memory.read(address, key)?.version ?? 0) + 1 };
     return memory.write({ ...claim, sig: voice.sign(Tools.canon(claim)) });
   };
-  put('chain/pk', Buffer.from(voice.pk).toString('hex'));
+  put('chain/pk', Bytes.hex(voice.pk));
   put('chain/nextPkHash', voice.nextPkHash);
   put('program', program ?? '({})');
   put(`keyring/${Tools.address(voice.pk)}`, {
-    boxPk: Buffer.from(voice.boxPk).toString('base64'),
-    wrapped: Voice.sealTo(voice.boxPk, root.toString('base64')),
+    boxPk: Bytes.base64(voice.boxPk),
+    wrapped: Voice.sealTo(voice.boxPk, Bytes.base64(root), cipher),
   });
   const written = program === undefined ? undefined : Program(program);
   return Compartment({
@@ -372,6 +449,7 @@ const make = ({ memory, voice, address, program }) => {
     address,
     root,
     classOf: (key) => written?.classOf(key) ?? coreClass(key),
+    cipher,
   });
 };
 
@@ -379,6 +457,7 @@ const Registry = ({
   memory,
   adminMine,
   address,
+  cipher,
   deliver,
   modules,
   modulesFor,
@@ -388,6 +467,7 @@ const Registry = ({
   vouched,
   attest,
   watch,
+  extended,
 }) => {
   const live = new Map();
   const stranded = (at, written) => {
@@ -416,6 +496,7 @@ const Registry = ({
     );
     const door = Being({
       address: at,
+      cipher,
       deliver,
       modules: modulesFor(voice, declared),
       span,
@@ -452,7 +533,7 @@ const Registry = ({
       }
       const voice = Voice();
       const address = Tools.address(voice.pk);
-      const mine = make({ memory, voice, address, program });
+      const mine = make({ memory, voice, address, program, cipher });
       for (const [key, value] of Object.entries(data)) {
         if (mine.write(key, value) === undefined) {
           forget(address);
@@ -488,7 +569,11 @@ const Registry = ({
       if (stranded(address, written).length > 0) {
         return undefined;
       }
-      return adminMine.write('program', program) === undefined ? undefined : address;
+      if (adminMine.write('program', program) === undefined) {
+        return undefined;
+      }
+      extended?.();
+      return address;
     },
     upgrade: ({ address: target, program }) => {
       if (target === address) {
@@ -551,4 +636,4 @@ const Registry = ({
   });
 };
 
-export { Being, Compartment, Registry, SUCCESSION, make, rootFor, spend };
+export { Being, Compartment, Registry, SUCCESSION, make, rootFor, spend, successionOf };