nervur 0.11.0 → 0.13.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
@@ -134,6 +160,17 @@ after. Both are custody's own calls on the shelf, never doors — which is
 what running-is-custody looks like from the outside, stated rather than
 hidden.
 
+`unproven()` is custody's third call, and it is a read: the addresses whose
+writes have stopped proving, with when each was first and last seen and how
+many writes have been refused. A write is proven against the key on the
+being's `chain/pk` cell, so whoever holds the shelf can overwrite that cell
+and freeze a being's memory while it answers on, correctly signed and
+indistinguishable to every caller. The ground records that in its own host
+rows under `ground/` — no being reads them, nothing goes over the wire — and
+this is where a host reads them back. Show it to whoever operates the
+machine; a ground that has stopped proving its own writes is a custody
+incident, not a bug.
+
 **`serve` is the client, and it has four faces of one door.** `pointer(at)`
 is a plain object with one function per field, generated from the schema that
 caller is allowed to see. `gql(at)` is the raw document. `mcp(at)` is the
@@ -215,7 +252,8 @@ silence, and silence is something local delivery never answers with.
   activates and destroys, reachable only through the admin being.
 - [admin.mjs](admin.mjs) — the administrative program every ground installs
   for itself, aliased `Ground`: census, create, activate, destroy, upgrade,
-  alias, attest, and behind `SELF` alone invite, drop and extend. Upgrade is
+  alias, attest, invite, drop, wear, and behind `SELF` alone extend; `wears`
+  answers any stranger with the livery being the ground wears. Upgrade is
   custody moving the one cell that was always the core's to move: the
   program is replaced in place — address, cells, refs and chain surviving —
   refused whole when a cell the being holds would go undeclared, and visible

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/admin.mjs

@@ -1,7 +1,10 @@
 const ADMIN = `({
   name: 'nervur.ground',
   needs: { modules: [{ module: 'memory', contract: 'nervur.memory' }] },
-  memory: { 'aliases/*': { type: 'String', class: 'data' } },
+  memory: {
+    'aliases/*': { type: 'String', class: 'data' },
+    wears: { type: 'String', class: 'data' },
+  },
   interface: \`
     input RefInput { address: String!, nextPkHash: String, rights: String }
     type Resident { address: String!, alias: String, digest: String, active: Boolean! }
@@ -11,6 +14,7 @@ const ADMIN = `({
       aliasOf(name: String!): String   @rights(is: [SELF, MEMBER])
       attest(module: String!): Boolean @rights(is: [SELF, MEMBER])
       opened: Boolean                  @rights(is: [SELF, MEMBER, STRANGER])
+      wears: String                    @rights(is: [SELF, MEMBER, STRANGER])
     }
     type Mutation {
       invite(address: String!, nextPkHash: String, rights: String): Boolean @rights(is: [SELF, MEMBER])
@@ -22,6 +26,7 @@ const ADMIN = `({
       destroy(address: String!): String                    @rights(is: [SELF, MEMBER])
       upgrade(address: String!, program: String!): Boolean  @rights(is: [SELF, MEMBER])
       alias(name: String!, address: String!): Boolean       @rights(is: [SELF, MEMBER])
+      wear(address: String): Boolean                        @rights(is: [SELF, MEMBER])
     }
   \`,
   resolvers: {
@@ -37,6 +42,7 @@ const ADMIN = `({
       aliasOf: (_, { name }, { modules }) => modules.memory.read('aliases/' + name),
       attest: (_, { module }, { registry }) => registry.attest(module),
       opened: (_, __, { modules }) => modules.memory.list('refs/').length > 0,
+      wears: (_, __, { modules }) => modules.memory.read('wears') ?? null,
     },
     Mutation: {
       invite: (_, { address, nextPkHash, rights }, { modules }) =>
@@ -66,6 +72,10 @@ const ADMIN = `({
         registry.upgrade({ address, program }) !== undefined,
       alias: (_, { name, address }, { modules }) =>
         modules.memory.write('aliases/' + name, address) !== undefined,
+      wear: (_, { address }, { modules }) => {
+        modules.memory.write('wears', address ?? undefined);
+        return modules.memory.read('wears') === (address ?? undefined);
+      },
     },
   },
 })`;